Documentation menu

Fabrics and swatches

Tier 2. With fabric entries, the product page shows a fabric picker: named swatches grouped by grade, each grade's surcharge and the weeks it adds, and a panel with every fabric, search, color and feature filters, a large preview with zoom, care notes and a sample button.

The fabric picker: Fabric: Oat Linen, Grade A's named swatches, the folded rows of Grade B (+$300), Grade C (+$600, adds 4 weeks) and Grade D (+$1,200, adds 6 weeks), and the links 40 fabrics for this piece and Order a free sample
The fabric picker, with each grade's surcharge and added weeks (Treadle, Harlow sofa).
The fabric panel, Choose a fabric, 40 fabrics: search, color and feature chips, grade headings with their notes, and a large preview of Forest Velvet with its grade, composition, lead time, care and Order a free sample
The fabric panel with every fabric for the piece (Treadle, Harlow sofa).

How it fits together #

  • You create one fabric entry per fabric you sell, with its name, swatch, grade, composition and care.
  • Each fabric belongs to a grade entry ("Grade A, Performance linen"). Grades group the swatches and can carry a lead time, which adds weeks to the arrival.
  • On each product, the Fabric option is linked to the product metafield custom.fabrics. Shopify then creates one option value per fabric you pick, named after the fabric, and keeps the metafield in sync.
  • Treadle reads the metafield, matches each option value to its fabric entry by name, and draws the picker.

One fabric entry serves every product and the sample product. Rename a fabric once and every product follows.

1. Create the definitions #

Create them in this order. The full field list is in the definitions reference.

Fabric grade #

  1. Go to Settings > Metafields and metaobjects. Under metaobject definitions, click Add definition.
  2. Name: Fabric grade. Check that the type reads fabric_grade.
  3. Add the fields: Name (Single line text, required), Sort order (Integer), Description (Multi-line text), Price note (Single line text), Lead time (Metaobject, one entry, Lead time).
  4. Check that Name is the display name (Shopify uses the first text field unless you change it). Tick Storefronts under Access, and click Save.

If you skipped lead times, create the Lead time definition first or leave out the Lead time field for now.

Fabric #

  1. Click Add definition again. Name: Fabric. Check that the type reads fabric.
  2. Add the fields from this table. Check every key.

    Field nameTypeKey
    NameSingle line text, one value, requiredname
    Swatch imageFile, one file, images only, requiredswatch_image
    Swatch colorColorswatch_color
    Large imageFile, one file, images onlylarge_image
    GalleryFile, list of files, images onlygallery
    GradeMetaobject, one entry, Fabric gradegrade
    MaterialSingle line text, one valuematerial
    Color familySingle line text, list of valuescolor_family
    FeaturesSingle line text, list of valuesfeatures
    CompositionSingle line text, one valuecomposition
    CareRich textcare
    Lead timeMetaobject, one entry, Lead timelead_time
    Sample variantProduct variant, one variantsample_variant
  3. Check that Name is the display name. Shopify uses the first text field unless you change it, so add Name first. This matters: linked option values take their names from the display name.
  4. Tick Storefronts under Access, and turn on Active-draft status.
  5. Click Save.

The product's fabric list #

  1. Go to Settings > Metafields and metaobjects > Products and click Add definition.
  2. Name: Fabrics. Namespace and key: custom.fabrics.
  3. Select type > Metaobject, choose List of entries, and pick the Fabric definition.
  4. Tick Storefronts under Access. Click Save.

2. Add grades and fabrics #

  1. Go to Content > Metaobjects > Fabric grade and add your grades, for example:

    NameSort orderPrice noteLead time
    Grade A, Performance linen1IncludedMade to order, 6–8 weeks
    Grade B, Bouclé and weaves2From +$300Made to order, 6–8 weeks
    Grade C, Velvet3From +$600Special order, 10–12 weeks

    Grades that take no longer than your products can leave Lead time empty. A grade adds its Min weeks less the product's, so Grade C above adds 4 weeks to a 6–8 week sofa. See lead times.

  2. Go to Content > Metaobjects > Fabric and click Add entry for each fabric. Fill in at least Name, Swatch image and Grade. Keep the status Active.

Fabric names must be unique, because the theme matches by name. "Oat Linen" and "Oat linen" count as different names.

Do this once per product. You can't do it with a product CSV import: Shopify imports a linked custom metafield column as a plain text option.

New product #

  1. Open the product in Products.
  2. In the Variants card, click Add options like size or color.
  3. Option name: Fabric.
  4. Click the connect icon next to the option name (the dynamic source icon), and choose Fabrics (custom.fabrics).
  5. Select the fabrics this product comes in. Their order here is the order shoppers see.
  6. Click Done, then add your other options, such as Size or Leg finish.
  7. Set prices for each variant. Fabrics in a more expensive grade need higher variant prices: Treadle shows "+$300" by comparing variant prices, so the price difference has to exist in the variants.

    Put an included fabric first, so the product opens on its cheapest variant. Keep the product at 250 variants or fewer: 40 fabrics × 3 sizes × 2 leg finishes is 240. See plan your variants.

  8. Click Save.

Existing product with a plain-text Fabric option #

Shopify can't mix linked and plain values in one option. Connecting the option replaces its values with fabric entries. Try it on a duplicate of the product first, then check variant prices, SKUs and inventory before you do it on the live product.

After linking #

  • custom.fabrics fills itself in the same order as the option values. You can't edit it directly; change the option instead.
  • Adding a fabric to the product: edit the option and select the new entry.
  • Renaming a fabric entry renames the option value on every product. On products with hundreds of variants this can take up to two minutes.
  • A product can list up to 250 fabrics. That's the most the theme can read for one product. In practice the variant budget is smaller: every fabric multiplies the other options. Sell a curated set per product; the fabric library still shows every fabric.

4. Check the picker settings #

In the theme editor, open Theme settings > Fabrics and samples:

  • Fabric option names: comma-separated option names that use the fabric picker. The default is "Fabric, Upholstery, Material, Finish, Cushion fabric". Matching ignores capitals. If a product has two matching options, the first one uses the picker.
  • Fabric list metafield: custom.fabrics unless your data uses another key.
  • Fabric metaobject type: fabric unless your definition has another type.

Then open a product page and click the Variant picker block in the Product section:

  • Swatches per row: 4 to 8. A fabric's name wraps between words only, never inside one. When the longest word in your fabric names wouldn't fit a swatch at this number, the grid shows fewer swatches per row, as it often does on a phone.
  • Swatches per grade: 3 to 12. How many swatches the open grade shows on the page before the panel link.
  • Size options: how sizes are shown. See blocks.
  • Show sample buttons and Button label: see samples.

What shoppers see #

  • "Fabric: Oat Linen" with the composition below it.
  • The selected fabric's grade is open, with its named swatches. Each swatch shows its surcharge over the cheapest fabric; included fabrics show no "+$0", and the grade heading says "Included" once.
  • Every other grade is one folded row with its surcharge and the weeks it adds: "Grade C, Velvet · +$600 · adds 4 weeks". Opening a row shows its swatches.
  • 150 fabrics for this piece opens the panel (on the sample product, set in Theme settings > Fabrics and samples > Sample product, it reads "150 fabrics"): a side panel on desktop and a full-screen sheet on phones. It loads only when opened, so it doesn't slow down the page.
  • The sample link sits beside it, for the selected fabric. See samples.
  • A fabric that isn't made with the current size or finish gives its reason instead of a price: "Not offered with Corner, 280 cm". A leg finish not made in the selected fabric says "Not made in leather", from the fabric's Material. A variant that's sold out says "Sold out".
  • Product cards show the first fabric swatches and "+145" for the rest. The number shown is set in Theme settings > Product cards > Swatches to show.
  • When the product's photos show another fabric, the photo says "Shown in Cream Bouclé", with the price difference if that fabric is in another grade. See custom.shown_fabric in the definitions reference.
The fabric panel on a phone: search, color chips, Grade A's swatches, and Oat Linen at the bottom with Order a free sample and Done
The fabric panel on a phone (Treadle).

Other places that use fabrics #

  • Fabric strip section: a numbered swatch schedule (01, 02 ...) with each fabric's name and grade, beside a heading and buttons. Set Fabrics from a product to show that product's fabrics in order, or leave it empty to show the first entries of your fabric list. Fabrics without a swatch photo are left out when any fabric has one.
  • Hero section, layout "Text, image and material grid": a grid of swatches beside the image, from Fabrics from a product.
  • Heading blocks: type [fabric_total] to show your exact number of fabrics ("150 fabrics to sample"), or [fabric_count] for the number rounded down to ten ("Over 140 fabrics"). Until you have fabric entries, the heading shows a short fallback instead.
  • Fabric library page: every fabric, grouped by grade, with sample buttons.
  • "Materials and care" detail row: the selected fabric's swatch, grade, composition, features and care. See dimensions and detail rows.

Without fabric entries (tier 0) #

Options that aren't linked to custom.fabrics render as buttons. If you connect an option to one of Shopify's category metafields, such as Color, and the values have swatch images or colors, Treadle shows those swatches instead. This works with no setup in the theme, but there are no grades, no fabric panel and no samples.

Troubleshooting #

  • The product shows plain buttons instead of swatches. Check that the option name is in Fabric option names, that the option is linked to custom.fabrics, and that the Fabric definition has Storefronts access. In the theme editor, an unconnected picker shows the note "Connect fabrics to show the fabric picker".
  • One fabric shows as a text button. Its entry is set to Draft, or the option value name doesn't match any fabric name. Set it to Active.
  • Swatches show but no grade headings. The fabrics have no Grade, so they show in one group.
  • "+$300" doesn't show. The variants for that fabric have the same price as the cheapest one.
  • A grade row says "adds" a number of weeks you didn't expect. The grade's lead time Min weeks are compared with the product's. Check both entries.
  • A fabric says "Sold out". Its variants track inventory at 0. Turn off Track quantity on made-to-order variants.