Keystone Documentation

Appearance

CSS Class & CSS ID ​

Attach your own CSS class or HTML ID to a single option, so you can target just that option with custom CSS or theme code.

Overview ​

Every option type has two optional fields under Advanced Settings: CSS class and CSS ID. Whatever you enter is applied to that option's outer container on the product page — the element that wraps the label, the control, and any validation message.

Both fields are empty by default and change nothing until you fill them in. Existing options are unaffected.

Use them for:

  • Targeting one specific option with theme CSS, when the app's Customization settings don't go far enough
  • Hooking an option up to your own JavaScript
  • Applying a layout tweak (width, order, spacing) to a single option rather than all of them
SettingOptions (default)What it controls
CSS classtext (empty)One or more class names, separated by spaces, added to the option's container. In-app help: Add your own CSS class(es) to this option so you can target it with custom CSS. Separate multiple classes with spaces.
CSS IDtext (empty)A single HTML id on the option's container. In-app help: Add your own HTML ID to this option so you can target it with custom CSS. Use a value that is unique on the page.

Both fields are available on every option type, in the same place under Advanced Settings.

How to Add a CSS Class or ID ​

  1. Navigate to Option Sets and open your option set
  2. Click the option you want to target
  3. Click Advanced Settings below the option label
  4. Enter a name in CSS class, CSS ID, or both
  5. Click Save in the contextual save bar
  6. Check the result in the editor's live preview, or view the product page source and look for your class/ID on the option's container

What Gets Rendered ​

The values land on the option's wrapper element, alongside the app's own classes:

html
<div id="gift-note" class="key_option_wrapper my-custom-class" data-option-type="shorttext">
  <!-- label, input, validation message -->
</div>

Because the wrapper encloses the whole option, a rule like .my-custom-class { grid-column: span 2; } affects the label and the control together.

Typing the Value ​

Type the name only — the leading . or # is optional.

Neither . nor # can legally appear inside a class name or an ID, so both characters are treated as separators wherever they show up. That single rule handles every way merchants tend to paste selectors:

What you typeCSS class field producesCSS ID field produces
my-classmy-classmy-class
.my-classmy-classmy-class
#my-idmy-idmy-id
promo featuredpromo featured (two classes)promo (first token only)
.a.ba b (two classes)a
..xxx
(empty or only spaces)nothing renderednothing rendered

The field decides, not the prefix

Whether a value becomes a class or an ID depends on which field you typed it into, never on the prefix you used. #promo in the CSS class box still becomes the class promo; the prefix is stripped and never survives into the HTML.

An ID is a single token

An HTML id can't contain spaces, so only the first token of the CSS ID field is kept — promo featured saves as promo. Use the CSS class field when you want more than one hook.

Also make sure the ID is unique on the page. If the same option set renders more than once, or two options share an ID, your CSS will match unpredictably.

Normalization runs both on save and again at render, so the stored value, the admin field, the API payload, and the rendered HTML always agree.

Behavior Notes ​

  • Empty means nothing. Leaving a field blank — or entering only spaces — saves nothing and adds no attribute to the storefront HTML
  • The editor preview matches the storefront. Your class and ID appear in the option editor's live preview as well as on the product page
  • Duplicating an option carries the values over. The copy gets the same class and ID, so remember to change the ID if you rely on it being unique
  • Changing an option's type resets both fields, the same as the other advanced settings