Metafields
Metafields are extra fields you add to products, variants and collections in your Shopify admin. Kyoto reads a few of them so each product can show its own second name, maker, material, cut-out picture or color field, without a separate template for every product.
All of them are optional. When a metafield is empty or doesn't exist, Kyoto falls back to a block setting or simply leaves that line out.
The metafields Kyoto reads
The Namespace and key must be typed exactly as shown, including the British spelling of field_colour.
| Namespace and key | Add it to | Type | Used by |
|---|---|---|---|
custom.title_ja | Products | Single line text | The second name in the Museum label block (shown in Japanese type) |
custom.made_in | Products | Single line text | Made in row of the Museum label |
custom.maker | Products | Single line text | Maker row of the Museum label (falls back to the product's vendor) |
custom.material | Products | Single line text | Material row of the Museum label |
custom.note | Products | Single line text | Note row of the Museum label |
custom.cutout | Products | File (images only) | The product's cut-out .png in the Product shelf section and the Color field with a shelf collection banner |
custom.height | Variants | Decimal or Integer | The number of each size in the Size ruler (in the unit you set in the block) |
custom.size_label | Variants | Single line text | The small hint under each name in variant cards, for example "18 cm" |
custom.field_colour | Products, Variants, Collections | Color | The pale color field behind the product (media stage, collection grid, product shelf) or behind the collection banner's shelf |
Kyoto also reads standard metafields that Shopify or your apps fill in:
| Metafield | Filled by | Used by |
|---|---|---|
Product subtitle (descriptors.subtitle) | You, after adding Shopify's standard Product subtitle definition | Show subtitle on product cards |
Rating and rating count (reviews.rating, reviews.rating_count) | Your reviews app | Show rating on product cards, the Rating block and the Reviews section |
Two settings take a metafield you name yourself (as namespace.key): Countdown metafield in Theme settings > Product cards (a date and time), and the Compare row block of the Product comparison section. Show price after coupon in Theme settings > Region and language reads custom.coupon_price (Money).
How to create a metafield
- In your Shopify admin, go to Settings > Metafields and metaobjects.
- Choose Products, Variants or Collections.
- Select Add definition.
- Enter a Name, for example "Field colour".
- In Namespace and key, replace the suggested value with the exact namespace and key from the table, for example
custom.field_colour. - Select Select type and choose the type from the table (for example Color). For
custom.cutout, choose File and allow images only. - Select Save.
Then fill the value on each product: open the product in Products, scroll to Metafields and enter the value. Variant metafields are on each variant's page.
You can also start from a product: open it and select Add definition in its Metafields card.
Connecting other metafields
Most text and image settings in Kyoto can be connected to any metafield, so you can build your own per-product content. Next to a setting in the theme editor, select the Connect dynamic source icon and pick the metafield. Examples:
- Chip 1 and Chip 2 in the Media stage block: connect a product metafield to give each product its own label on the photo.
- Display heading and Feature number in the Collection banner: connect collection metafields.
- Rows of the Product details section and the Specifications block: connect product metafields for dimensions, weight or care.
Example: one product, fully described
A hand-thrown bowl with three sizes and two glazes:
| Where | Value |
|---|---|
Product custom.title_ja | 飯碗 |
Product custom.made_in | Mashiko, Tochigi |
Product custom.maker | Kobo Asano |
Product custom.material | Stoneware, ash glaze |
Product custom.cutout | bowl-cutout.png |
Product custom.field_colour | #E3ECD9 |
Variant "Small" custom.height / custom.size_label | 6 / 6 cm |
Variant "Medium" custom.height / custom.size_label | 7.5 / 7.5 cm |
Variant "Large" custom.height / custom.size_label | 9 / 9 cm |
With a Museum label block, a Size ruler block (Size option names: Size, Unit: cm) and the variant picker set to Cards, the product page shows the Japanese name, the origin and maker, a ruler that grows from 6 to 9 cm and size cards with "6 cm", "7.5 cm" and "9 cm" under the names, all from the product's own data.