⚙️ `options` Object

The options field inside getCollection() lets you deeply control how collection, product, and variant metafields are parsed, casted, and transformed — without extra logic in your UI.

Useful for:

Creating derived fields
Formatting outputs for the frontend
Handling rich text and file references
Enabling camelCase keys for JavaScript use

✨ Available Options

type Options = {
  camelizeKeys?: boolean;
  resolveFiles?: boolean;
  renderRichTextAsHtml?: boolean;

  transformCollectionMetafields?: (
    raw: Record<string, Record<string, string>>,
    casted: Record<string, any>,
    definitions: ResolvedMetafieldInfo[]
  ) => Record<string, any> | Promise<Record<string, any>>;

  transformProductMetafields?: (
    raw: Record<string, Record<string, string>>,
    casted: Record<string, any>,
    definitions: ResolvedMetafieldInfo[]
  ) => Record<string, any> | Promise<Record<string, any>>;

  transformVariantMetafields?: (
    raw: Record<string, Record<string, string>>,
    casted: Record<string, any>,
    definitions: ResolvedMetafieldInfo[]
  ) => Record<string, any> | Promise<Record<string, any>>;
};

🐫 `camelizeKeys`

camelizeKeys: true;

If true, all metafield keys will be converted from namespace.key to camelCase format (e.g., custom.weight → customWeight).

Useful when working with frontend frameworks or API outputs that prefer camelCase.

📄 `resolveFiles`

resolveFiles: true;

If true, any File metafields will be expanded to return originalSrc, altText, and other image/file attributes.

Applies to:

Collection metafields
Product metafields
Variant metafields

📝 `renderRichTextAsHtml`

renderRichTextAsHtml: true;

If true, Rich Text metafields will be returned as HTML strings — ready for use with dangerouslySetInnerHTML or your favorite renderer.

If false, raw data will be returned for custom rendering.

🔧 `transformCollectionMetafields`

transformCollectionMetafields: (raw, casted, definitions) => {
  return {
    ...casted,
    extraTagline: `${casted["custom.title"]} - Featured`,
  };
};

Customize or extend collection-level metafields. Useful for when you're attaching metadata directly to a collection.

🔧 `transformProductMetafields`

transformProductMetafields: (raw, casted, definitions) => {
  return {
    ...casted,
    customMeta: `${casted["custom.brand"]} - ${casted["custom.weight"]} kg`,
  };
};

Allows you to customize, rename, flatten, or extend the parsed product-level metafields.

You get:

raw: original unparsed metafields
casted: parsed values (by definition)
definitions: full metafield metadata

Return a new object to override or extend the result.

🧬 `transformVariantMetafields`

transformVariantMetafields: async (raw, casted, definitions) => {
  return {
    ...casted,
    enriched: true,
  };
};

Same as transformProductMetafields, but for variant-level metafields. You can even use await inside this function to fetch related products, images, or external data.

🧠 Pro Tip

Use all three transforms together to flatten nested structures, add summaries, or preload related entities (like bundled products or references) for blazing-fast rendering.

✅ Next: Types Reference →