> For the complete documentation index, see [llms.txt](https://staylime.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://staylime.com/docs/avante-themes/features-and-advanced-setup/custom-options.md).
# Custom options
Collect engraving text, gift messages, measurements or uploaded files in the buy area — saved with the order as line item properties.
Some products need something from the customer that a variant cannot express: an engraving, a gift message, a set of measurements, a logo file to print. Custom options collect it right in the buy area and attach it to the order, with no app and without multiplying your variant count. For made-to-order and personalised products this is usually the difference between an enquiry by email and a completed checkout.
***
### How to add
1. Go to **Online Store → Themes → Customize** and open your product template.
2. In the **Product overview** section, click **Add block** and pick one of the ten **Custom options** blocks.
3. Fill in **Option name** — this is the name the value will carry in the order. It must be unique within the product.
4. Fill in **Option label** — the wording the customer actually reads.
5. Add as many blocks as the product needs, and drag them into the order you want.
Custom options are available in three sections — **Product overview**, **Featured product** and **Quick view** — and all ten types work in all three.
{% hint style="warning" %}
If **Option name** is empty, the block is not displayed at all and nothing is saved with the order. This is the single most common reason a field "disappears" from the product page.
{% endhint %}
***
### Good to know
* **Custom options never change the price or the stock.** They are pure data attached to the line item — there is no pricing logic and no inventory behind them, so an option value can never sell out and can never add a surcharge. If a choice has to cost more or has to be counted in inventory, make it a variant or a separate product.
* **"Show for option value" discards what the customer already typed.** This setting, new in 16.0, shows a block only when the selected variant has a matching option value. When the customer switches to a variant that hides the block, the field is disabled and removed from the form — anything typed into it before the switch is silently dropped and will not appear in the order. Use it for choices that genuinely belong to one variant, not as a way to tidy up a long form.
* **"Show for option value" takes one value, not a list.** Enter a single option value such as `Red`. The match ignores letter case and surrounding spaces but must be the whole value — partial matches and comma-separated lists do not work. Leave it blank and the block is always shown.
* **Required fields are enforced in the browser only.** The theme blocks Add to cart, highlights the field and scrolls to it, which handles every real customer. It is not a server-side guarantee, so do not rely on it for anything legally or financially critical.
* **Several types always submit a value, even when the customer ignores them.** Dropdown pre-selects its first option, Pills and Color pills pre-select the first pill, Date pre-fills today's date, and the Color picker always starts on black. None of them has an empty state, so expect a value on every order.
* **Measurement writes one property per field.** A Measurement block named `Fit` with fields `Chest[cm]` and `Waist[cm]` produces two properties, `Fit - Chest` and `Fit - Waist`, not one combined line.
* **Two blocks with the same Option name collide.** They write to the same property and only one value survives. Names have to be unique across the whole product form.
* **On the Checkbox type, the minimum-selections setting overrides "Make required".** If you set a minimum above zero, that rule is what the customer has to satisfy.
* **File upload accepts up to 5 MB and any file type.** The size is checked in the browser, and there is no restriction on extensions — if you need PDFs only, say so in the label or the tooltip.
* **Color pills here are not the variant color pills.** The restriction that variant swatches only appear when the option is named Color or Colour does not apply to the Custom options version — it always renders swatches. Each value is matched against your swatch configuration first, then against an image named after the value in **Content → Files**, and finally interpreted as a CSS colour name.
* **Empty optional fields are removed before the item is added to the cart**, so blank values never clutter the order.
***
### Customization ideas
* Use **Info tooltip** rather than a long label. A short label with a tooltip explaining the engraving character limit reads far better than a two-line question.
* Combine a **Checkbox** ("Add gift wrapping") with a **Multi line text** ("Gift message") and show the message field only when it is relevant by keeping the label explicit — the two blocks stay independent, so the message is always optional.
* For made-to-measure products, one **Measurement** block with all the dimensions produces a tidy set of properties on the order that your production team can read at a glance.
* Use **Show for option value** on a finish-specific question — for example an engraving font that only applies to the metal variant.
* Set **Max character length** on text fields to whatever your engraving machine or print area actually allows, so the limit is enforced before the order exists rather than in an apology email afterwards.
***
### Settings
Settings every type shares
**Option name** — the property name saved with the order. Must be unique; if it is empty the block is not displayed and the value is not saved.
**Option label** — the text the customer sees above the field.
**Show for option value** — display the block only when the selected variant has this option value. Leave blank to always show it.
**Info tooltip** — a short explanation shown next to the label.
**Label size**, **Text size**, **Top spacing** and **Mobile top spacing** control the appearance of the block.
The ten types
**Pills** — a row of selectable buttons. You supply the values and choose a layout: adapted to the text, two in a row stretched, or three in a row stretched. The first pill is selected by default.
**Color pills** — the same as Pills but rendered as colour swatches, with an option to show the colour name.
**Color picker** — a free colour input. It always has a value, starting at black.
**Dropdown** — a select list of your values. It has no required setting because the first value is always selected.
**Checkbox** — one or more checkboxes, laid out in two columns or in a row. Offers **Make required** and a **Minimum number of selections required**, plus a matching maximum; when a minimum above zero is set, it takes over from Make required.
**Single line text** and **Multi line text** — free text, with **Make required** and an optional **Max character length**.
**Measurement** — several numeric fields in one block, written as a list with units in square brackets, for example `Chest[cm], Waist[cm], Hip[cm]`. Has **Make required** (which applies to every field), **Max character length** and a one-column or in-a-row layout.
**Date** — a date picker. **Minimum number of days from today** pushes the earliest selectable date forward, and an optional last allowed date in `YYYY-MM-DD` format closes the window. It pre-fills with the earliest allowed date.
**File upload** — a drag-and-drop file field with **Make required**. Maximum 5 MB, any file type.
***
### Best practices
* Name options the way you want to read them on the packing slip. The **Option name** is what your team sees in the Shopify order, not the label.
* Keep required fields to the genuine minimum. Every required field is one more reason to abandon the cart.
* Place the blocks above the Buy buttons. A field the customer only notices after the error message is a field in the wrong place.
* Test the whole form in **Quick view** as well as on the product page — the blocks exist in both, and a form that fits the product page can feel cramped in the pop-up.
* Before relying on **Show for option value**, click through every variant and confirm the right fields appear. It matches one exact value, so a typo simply means the block never shows.
***
### Related
* [Default product](/docs/avante-themes/templates/default-product.md)
* [Variant selector](/docs/avante-themes/theme-settings/variant-selector.md)
* [Linked Products](/docs/avante-themes/features-and-advanced-setup/linked-products.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://staylime.com/docs/avante-themes/features-and-advanced-setup/custom-options.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.