# Materials and free samples

Chapter 8 of the Atelier user guide.

Furniture is bought by its materials. Atelier shows them as round chips with a large close-up, lets shoppers filter many materials by family, and lets them order free samples before they commit, with a sample box that never lets them order more than you can send.

## What shoppers see

* **Material chips** in the buy box for every option named in **Material option names**: 44px circles showing each material's swatch. Hovering or focusing a chip previews it in the close-up; moving away brings back the selected one.
* **Family tabs** above the chips when an option has more values than **Family tabs from** (8 by default, on the Variant picker block) and they belong to two or more families: "Bouclé and wool · Leather · Linen and cotton", starting on the selected material's family. The legend counts the values ("Upholstery: Bouclé ivory, 14 options").
* **The close-up** under the chips: the selected material's swatch at 104px, its name, summary and origin, and the sample action. The image is the Material entry's `swatch`, else the option value's own swatch image, else its swatch color, else a stone square with the material's initial.
* **The sample action**, the close-up's last line:
  * "Order a free sample" (or "Order a sample · $5.00" when the sample variant has a price);
  * "Adding…" while it is added; the cart count updates and a screen-reader announcement says "Bouclé ivory sample added to your cart." The drawer doesn't open, because the shopper is still choosing;
  * "Sample in your cart" with **View cart** once it's there (or if it already was);
  * "You have 5 samples, the most we can send at once." when the cart holds the maximum.
* **Order free samples**, a link under the buy buttons, jumps to the close-up's sample action, or goes to your samples page when the product has no material close-up.
* **Card chips**: product cards show small chips from the first option whose values have Shopify swatches (Theme settings › Product cards › Show swatches). Set swatches on the option values in admin (each value's swatch color or image); Material entries alone don't add chips to cards.
* **Material care**: a Collapsible row with its content set to **Material care** shows the selected material's `care` notes, falling back to its own content when the material has none.

## The Material library section

A stone band for your home page, a samples page, a collection or a product page. On the left: the kicker, heading ("Feel it before you choose it") and text, then the **sample box**: "Your sample box, 2 of 5", a slot for each sample the cart may hold (filled slots show the sample's swatch) and **Review your samples**, which opens the cart drawer. On the right: family tabs with counts, and a grid of material tiles, each with a square close-up, the name, the summary and **Add sample** (or "In your sample box").

| Setting | Default | What it does |
| --- | --- | --- |
| Kicker, Heading, Text | "Material library", "Feel it before you choose it" and a line about five free samples | Rewrite the text to match your limit and your sample policy |
| Materials | Empty | Up to 24 Material entries, in the order you pick them. With none chosen the section shows nothing to shoppers (the editor shows four placeholder tiles). |
| Show family tabs | On | **All** plus one tab per `family`, with counts; shown when the chosen materials span two or more families |
| Show the sample box | On | Shown when samples are on in Theme settings |
| Button label | "Review your samples" | The sample box's button |
| Columns on desktop | 4 | 3 or 4 |

The `page.samples` template that ships with every preset holds an intro, a Material library titled "Every material we work with" and a FAQ ("Sample questions"). Create a page called Samples, set its template to `page.samples`, choose its materials, and select it in **Theme settings › Materials and samples › Samples page**. The empty cart and the hero's "Order free samples" link point there.

## Settings

| Where | Setting | What it does |
| --- | --- | --- |
| Theme settings › Materials and samples | Material option names | Which options become material chips. Add your own words (Veneer, Marble, Glaze) and remove any you use for something else. |
| | Offer free material samples | Off hides every sample action, the sample box, the buy box link and the cart's samples group at once |
| | Most samples per order | 5 (1 to 10). The size of the sample box and the point at which the actions stop offering more. |
| | Sample product | The fallback product whose variant titles match your material names (chapter 7, step 4) |
| | Sample note in the cart | "Samples are posted separately, within two days." |
| | Samples page | Your samples page |
| Variant picker block | Show the material close-up | Off shows the chips without the close-up |
| | Show the free sample action | Off keeps the close-up without the action |
| | Family tabs from | 8 (4 to 20) |
| Buy buttons block | Show order free samples | The link under the buy buttons |

## Samples in the cart

Each sample is its own cart line, quantity 1, carrying two hidden properties: `_sample` and `_sample_for` (the product the shopper was looking at; empty from the library). In the cart drawer and on the cart page, samples are grouped after the other lines under **Samples** with "2 of 5, free" (or "2 of 5" when any sample costs something): a swatch, the material's name, "For the Arc lounge chair" or "From the material library", "Free" or the price, and a remove button. There is no quantity stepper, and if an app or the cart page raises a sample's quantity, the theme sets it back to 1. Your **Sample note** shows under the group.

A line counts as a sample when its product type is `Sample` or it carries the `_sample` property, so samples added by other means are counted too. When the cart holds only samples, checkout works as usual, with your shipping rates.

> **Note:** the limit is enforced by the theme's buttons, not at checkout. A determined shopper could add more through another route, so treat the limit as a guide and check large sample orders before you post them.

Untick **Offer free material samples** to turn samples off: the chips, family tabs and close-ups stay, and every sample action, the sample box, the links and the cart's samples group disappear.