Metafields on the page

Metafields hold the extra data of a Shopify product or variant: a material, a care guide, a spec sheet, a list of ingredients. Smootify shows them on the page straight from Shopify. Build the product page shows the basic attribute. This page covers the rest: what each type shows, lists, values in attributes, JSON, references, ratings and conditions.

Show a metafield

metafield="material" on an element inside smootify-product shows the product metafield custom.material. Here is the whole path, from the Shopify admin to the page:

1. In the Shopify admin, Settings › Custom data › Products: a definition named Material, with the namespace and key custom.material, the type Single line text, and Storefronts access on.
2. On a product, its Metafields card holds the value: Material = Linen. A review app writes Rating in its own namespace: reviews.rating = 4.5 out of 5.
3. In your component, inside smootify-product: metafield="material" shows Linen; metafield="rating" namespace="reviews" shows 4.5 and sets --metafield-rating to 90%.

• Namespace. Smootify reads the namespace custom unless you add namespace="…", for example namespace="reviews" for reviews.rating.
• Variant metafields. variant-metafield="…" shows a metafield of the selected variant, and changes with it, a video included.
• Where they work. metafield works inside smootify-product, on the product page and on product cards, and inside a cart line, where it reads the line’s product (Build the cart). variant-metafield works inside smootify-product and on variant cards (List the variants). Anywhere else, Smootify does not read the attribute.
• Empty values. When the metafield is empty or missing, the element is hidden. What you write in the markup stays as a placeholder until the value arrives. With data-fallback="…", the element stays and shows that text instead. An empty data-fallback is ignored, so a component can pass it a prop that most instances leave empty.

In the HTML before Smootify loads. To write a metafield in the page itself, list its key in the metafields option of the loader: the entry then holds it, such as p.metafields.material, and your markup can render it. Smootify still writes the live value from Shopify. See Content from Shopify.

What each type shows

Every type, list types included: metafield types.

Lists

A list of text, numbers, dates or measures is joined into one text, such as Cotton, Linen. Two ways to change that:

• separator=" / " joins the values with the text you write, spaces included. The default is a comma and a space.
• separator="repeat" makes one copy of the element per value. Design one item, and lay out the list as you like.

<div>
  <div metafield="ingredients" separator="repeat">Ingredient</div>
</div>

Lists of files, colours, URLs, links, ratings, references and metaobjects always make one copy of the element per item.

Values in attributes, decimals and colours

• data-attr="aria-label" writes the value into that attribute instead of the element’s content. It works for text, whole numbers, ratings and values from JSON. Use it for a label that screen readers read, a title, or an image’s alt.
• data-digits="1" rounds a decimal number, and the text of a rating, to that many decimals.
• Colours. A colour metafield writes no text. It sets the CSS variable --metafield-color on the element, and property="--badge-color" gives the variable another name. Use the variable in your styles, for example as a background colour, so the merchant can change a badge colour in Shopify. A list of colours makes one copy of the element per colour, each with its own variable.

JSON

A JSON metafield shows nothing until data-path points at a value:

• data-path="size.width" shows one value. Separate the keys with dots.
• data-path="colors.0" shows the first item of a list. Positions count from 0.
• A path that is not in the JSON hides the element.

<div>
  <div metafield="specs" data-path="size.width">0</div>
  <div metafield="specs" data-path="colors.0">Colour</div>
</div>

For several values of one metafield, you can also put data-path on elements inside a single metafield element, each with its own path. A path that leads to a list of objects repeats its element once per object, and the paths inside each copy start from that object. This makes a table of specs from JSON such as [{"label": "Height", "value": "90 cm"}].

Without any data-path, a JSON metafield is left to custom code: see Render a metafield yourself.

References

A metafield that references a product, a variant, a collection or a page shows it according to the element:

• on an <a>, it links to it (a variant link opens the product page on that variant);
• on an <img>, it shows its image;
• on an element without children, it shows its title.

Inside the element, reference="title", "url", "image", "handle", "description" (collections) and "body" (pages) show those parts. A part that the reference does not have is hidden. A list of references repeats the element once per reference.

Pages have no URL, so reference="url" gives no link on a reference to a page. The links of products, variants and collections follow the site’s trailing slash.

<a href="#" metafield="pairs_with">
  <img reference="image" alt="">
  <div reference="title">Product</div>
</a>

For product cards with a price and an add-to-cart button, use a smootify-product whose data-id names the metafield instead: see Product lists.

Metaobjects. Inside an element with a metaobject reference, metaobject="field" shows a field of the metaobject. A list repeats the element once per metaobject. On a link inside it, metaobject-url="/materials/{handle}" builds the link from the metaobject’s handle. More in Show metaobjects.

Ratings

A rating metafield, such as reviews.rating from a review app:

• on an element without children, shows the value as text, such as 4.5;
• always sets the CSS variable --metafield-rating on the element: the rating as a share of its scale, such as 90% for 4.5 out of 5.

An element with children keeps them and only gets the variable. For stars, put a fill inside it that holds the row of stars, with its overflow hidden and a width of var(--metafield-rating): it covers that share of the row. data-attr="aria-label" gives the value to screen readers.

<div metafield="rating" namespace="reviews" data-attr="aria-label">
  <div>★★★★★</div>
</div>

The review apps that write this metafield: Product reviews.

Show or hide by a metafield

if-metafield="key" shows an element only when the metafield says so, and unless-metafield="key" hides it. Both take namespace, and have a variant version: if-variant-metafield and unless-variant-metafield. For example, if-metafield="vegan" on a badge shows it only on products whose custom.vegan is true.

Every condition: product metafield conditions and variant metafield conditions.

Before you publish