POS styling API
On this page
Use this reference when you write CSS for the point of sale that has to keep working after
an upgrade. The CSS goes in a style block with POS in Channels
or in a <style> element in a POS view. Your styles keep working
when the POS is upgraded as long as they use only these four kinds of name:
- Component properties: settings a component reads, such as
--sc-button-bgfor a button’s fill. Use these first. - Parts: named pieces of a component, such as a button’s label, selected with
[part~='button-label']. Use a part when no property does the job. Some elements on a screen also have a name of their own, such as the cart’s Pay button. The component’s reference article lists them. - Attributes: which kind of a component it is, such as
data-varianton a button, or what state one of its parts is in, such asaria-currenton the row of a record table that is open, so you can style one kind or one state only. The component’s reference article lists each one with the values it takes, and the part it is on when that is not the component’s root. - Design tokens: the colors, fonts, and type scales every component is styled from,
such as
--sc-color-primary. Set one on:rootto change the whole POS at once. The POS design tokens reference lists them.
Together these are the POS styling API. Everything else is internal and can change in any
release: class names, IDs, data-* and ARIA attributes the component’s article does not
list, element types, and the structure of the markup. A part stays on an element that does
the same job. Where the element sits and the markup around it can change.
You do not need !important. Every published component loads its styles in cascade layers,
so a rule in your style block or view wins over them at any specificity. The exceptions are
listed under “What can’t be styled yet” on each component’s article. The rest of the POS’s
styles, including layout classes a screen adds to a component, are outside the layers and
follow normal specificity, which is one reason to leave layout alone.
Published components
| Component | What it covers | Available from | Reference |
|---|---|---|---|
| Button | Standalone buttons, such as the Pay button in the cart, the buttons on the payment screens, and the buttons in most dialogs | v22.0.4 | Button styling reference |
| Card | The tiles screens lay out, such as products in a products grid, the tiles of an action grid, and a bundle’s components | v22.0.10 | Card styling reference |
| Layout | How screens arrange cards and tiles, such as the products grid, the lists of records, and action grids | v22.0.8 | Layout styling reference |
| List button | The items of the navigation and of menus: each action item in the sidebar and the bar, the More button, the button that collapses the sidebar, the cart button on the bar, and the items a group opens | v22.0.14 | List button styling reference |
| Loading dots | The three pulsing dots beside a status that is still changing, such as the preparing state on an open order’s line | v22.0.14 | Loading dots styling reference |
| Media image | The images on product cards and action tiles, the thumbnails on cart rows and order items, the pictures in list items and the variants menu, and the gallery on a product’s screen | v22.0.13 | Media image styling reference |
| Menu | The menus the action navigation opens, such as a group’s items floating from the sidebar or the bar, and a group opened inside the More menu | v22.0.13 | Menu styling reference |
| Product price | The prices on product cards, in product lists and on variants, at the top of a product’s screen and a bundle’s screen, and on a bundle’s components | v22.0.7 | Product price styling reference |
| Record table | The tables of records in a list, such as the customers and orders lists, and the results of a quick search | v22.0.7 | Record table styling reference |
The Available from column shows the first release that carries the names.
Every other component has no parts or properties yet. CSS that reaches one has to select the app’s own classes, which are internal and can change in any release. See If what you need has no part yet.
Design tokens
The POS design tokens reference lists the values every component is styled from, grouped by what they are for, with examples. The tokens are part of the styling API from TBD. The names themselves go back further: each table in the reference shows the release that first carried the token.
Rules
- Use only the parts, attributes, and component properties listed on the component’s reference article, and the tokens listed on the POS design tokens reference.
- Select a part with
[part~='name'](how attribute selectors work). Always~=, never=or^=: an element can carry more than one part, and~=still matches it. - To style a part inside one component, write the component’s root part or name, a space,
then the part:
[part~='cart-checkout-button'] [part~='button-label']. The part after the space must belong to that component, as the reference article lists it. Nothing else goes around a part: no>,+, or~, no structural pseudo-classes such as:first-child,:nth-child(),:empty, or:has(), and never more than two parts. - To style one kind of a component, narrow the root part by an attribute the reference
article lists, inside
:where():[part~='button-root']:where([data-variant='filled']). One attribute per:where(); for two kinds at once, write two::where([data-variant='filled']):where([data-tone='primary']). Inside:where()the attribute does not make the rule stronger, so it ties with a rule for one named element, and the later rule wins. Write the rule for a named element after the rules for the kind. An attribute the reference article lists on another part, such asrecord-table-row[aria-current], narrows that part the same way:[part~='record-table-row']:where([aria-current='true']). - A part may end with a state pseudo-class (
:hover,:focus-visible,:active,:disabled) or a pseudo-element (::before,::after). - Do not select classes, IDs, element types, or attributes other than the listed ones. They are internal: selecting them works today, but it can break in any release.
- Prefer a component property to a plain CSS property when one does the job. The component
handles the rest, including how it looks when hovered or pressed. A component’s
properties cover what it draws inside itself too, such as
--sc-button-icon-sizefor a button’s icons. Set a property on the root part to change every instance, on the root part narrowed by an attribute to change one kind, or on a named part to change one instance. A property set on:rootreaches every component, unless something closer to the component sets it. To change every component at once, set a design token on:rootinstead. - A property applies to every kind of the component unless the rule narrows it away.
Every kind of button reads
--sc-button-bg, so setting it fordata-tone='primary'alone gives primary text buttons a fill too. Narrow by each attribute that matters. Size is a kind too:--sc-button-icon-sizeon the root part replaces the icon size of every button size, so narrow bydata-sizeto change one. A property set after a state, such as:where([data-variant='filled']):active, applies in that state only. - Change appearance only: color, background, border, radius, font, and inner padding.
Leave
display,position,order,width, and outer margin alone, because they depend on the screen around the component. - Your styles win over a published component’s own styles without
!important, except where the component’s reference article lists them under “What can’t be styled yet”. - Parts are for CSS only. Never select them from a script. Scripts use the POS actions through scAction.
If what you need has no part yet
- Check whether a design token or the Color field on a POS Action Item does the job. Tokens reach every screen, and Color reaches one action button.
- Raise a support case that names the screen and the element, and asks for a part or property. Parts are added to components as stores ask for them.
- If you go ahead with CSS that selects the app’s own classes, keep it in a style block of its own, note which screens it touches, and check those screens after every upgrade. It can stop working or style something else in any release.
When parts change
- New parts, attributes, properties, and tokens can arrive in any release. Each component’s article, and the design tokens reference, shows the release each one first shipped in.
- The markup around a part can change in any release, but the part stays on an element that does the same job.
- A part, property, attribute value, or token is only removed, renamed, or changed to mean something else in a major release. A release retires it first: the release notes say so, and the component’s article, or the design tokens reference, lists it under “Retired”, with what replaces it and the major release that removes it. It keeps working until that release, so you have until then to move your styles off it.
- The POS’s own look, such as the default colors and spacing, can change in any release. Your styles still apply, but the result can look different.
AI tools
If you use an AI tool to write your styles, give it this article and the articles for the components you want to change. To change the whole POS, also give it the POS design tokens reference. Ask the tool to use only the parts, attributes, properties, and tokens listed in those articles, and to tell you when a request needs anything else. Without these articles, the tool inspects the POS and uses whatever class names it finds, and those can change in any release. See Build POS with an AI agent for setting an agent up.
Component markup copied into a view
A view can copy a component’s markup, classes, and attributes to draw something that looks like it. That works, but it is not kept working between releases: the copied classes and structure can change in any release, and the copy has no parts unless it writes them itself.
Was this article helpful?
Thanks for your feedback! It helps us improve our docs.