Skip to content
Log in

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:

  1. Component properties: settings a component reads, such as --sc-button-bg for a button’s fill. Use these first.
  2. 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.
  3. Attributes: which kind of a component it is, such as data-variant on a button, or what state one of its parts is in, such as aria-current on 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.
  4. Design tokens: the colors, fonts, and type scales every component is styled from, such as --sc-color-primary. Set one on :root to 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

  1. 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.
  2. 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.
  3. 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.
  4. 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 as record-table-row[aria-current], narrows that part the same way: [part~='record-table-row']:where([aria-current='true']).
  5. A part may end with a state pseudo-class (:hover, :focus-visible, :active, :disabled) or a pseudo-element (::before, ::after).
  6. 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.
  7. 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-size for 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 :root reaches every component, unless something closer to the component sets it. To change every component at once, set a design token on :root instead.
  8. 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 for data-tone='primary' alone gives primary text buttons a fill too. Narrow by each attribute that matters. Size is a kind too: --sc-button-icon-size on the root part replaces the icon size of every button size, so narrow by data-size to change one. A property set after a state, such as :where([data-variant='filled']):active, applies in that state only.
  9. 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.
  10. 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”.
  11. 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

  1. 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.
  2. 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.
  3. 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?

Was this article helpful?