🧩 Custom Metafields

Shopify metafields allow you to add rich, structured content to your products, variants, collections, pages, and more. However, the Storefront API returns all metafield values as strings — even for numbers, dates, booleans, or JSON.

This SDK solves that by letting you define typed metafields, so they are automatically parsed and returned in the correct format.

🧠 Why use types?​

Shopify doesn't cast metafield values for you — everything comes back as a string:

With the SDK, you define your expected types using the CustomMetafieldDefinition format:

{
  field: "custom.warranty",
  type: "single_line_text"
}

From there, the SDK handles everything — parsing values, resolving references, converting to numbers or booleans, or even rendering rich_text as HTML.

🧬 Data Type Mapping​

Here’s a quick guide to map Shopify metafield types to SDK-supported type values:

📆 Date and Time​

📐 Measurement​

🔢 Number​

📝 Text​

🔗 Reference​

🧪 Other​

🧠 Advanced​

🛠 Defining your fields​

Metafields must be defined using the shape below:

interface CustomMetafieldDefinition {
  field: "custom.namespace_key"; // e.g., "custom.warranty"
  type: ShopifyCustomFieldType;
}

The SDK parses and organizes your data into a nested object like this:

metafields: {
  custom: {
    warranty: "10 years",
    weight: 12.5,
    documents: [{ id: "gid://shopify/File/...", url: "..." }]
  }
}

🔄 How casting works​

The SDK automatically converts raw string values using a utility called castMetafieldValue(), based on the type you define:

• decimal, money, rating → parsed as numbers
• true_false → parsed as booleans
• json → parsed as JSON
• date, date_and_time → cast to JavaScript Date
• rich_text → optionally rendered as HTML
• File → optionally resolved to object with url, alt, etc.
• Product, Page, etc. → parsed as references (or enriched in transformMetafields)

This makes your frontend code cleaner, safer, and type-friendly.

🧪 Example​

customMetafields: [
  { field: "custom.brand", type: "single_line_text" },
  { field: "custom.weight", type: "decimal" },
  { field: "custom.warranty", type: "single_line_text" },
  { field: "custom.short_description", type: "rich_text" },
  { field: "custom.certificates", type: "File" },
];

These values will be returned already parsed:

product.metafields.custom.weight; // → 12.5 (number)
product.metafields.custom.certificates[0].url; // → resolved file URL
product.metafields.custom.short_description; // → HTML string (if rendered)

📦 Advanced: resolveFiles and renderRichTextAsHtml​

To unlock extra features:

options: {
  resolveFiles: true,
  renderRichTextAsHtml: true
}

• resolveFiles: Automatically converts file GIDs to structured file objects
• renderRichTextAsHtml: Parses Shopify’s JSON schema into safe HTML

🔁 Want even more control?​

You can use transformMetafields or transformVariantMetafields to modify the final shape of the data — flatten it, add summaries, or even make conditional flags.

➡️ Learn how in Options →

Would you like to continue to Examples →?