POS style reference

It also lists behavior and layout toggles, such as the sidebar side and mobile footer.

It composes the rest of the chapter rather than repeating it:

• Run InStore POS API requests: authenticate and run the calls.
• Theme API reference: the GET, PUT, and PATCH endpoints and validation rules.
• Customize POS styles and behavior: the authoring guide these tables draw on.

How to target styles

Every visual change lands in one of three layers of the theme payload. Knowing which layer a change belongs to tells you where in the JSON it goes.

1. Global tokens: palette (colors), typography (text), shape (corner radius), spacing, and zIndex (stacking) at the top level. A token such as 'primary.main' is defined once here and referenced everywhere. Reuse the tokens the theme already defines wherever you can. For more information, see Reference palette tokens.
2. Per-component styling: under components.MuiX, using a styleOverrides slot or a variants entry. Most InStore surfaces are targeted by a nested class selector inside a slot, such as styleOverrides.<slot> then &.instore-Y (or & .instore-Y for a child), while a few are className variants. The "How to target" column below tells you which.
3. Behavior and global settings: under customTokens (InStore-specific layout flags), plus components.MuiDrawer.defaultProps.anchor for the sidebar side. To identify the supported layout flags and sidebar setting, see Behavior and global settings.

Every change lands in one of these three layers of the theme payload; the rest of this page shows which layer each surface uses.

• Component values resolve as MUI sx, so a numeric borderRadius or spacing is a theme multiple, not pixels. Use a string such as "8px" for an exact value. To understand how component override values resolve and which palette token strings are supported, see the note in the authoring guide.
• A components.MuiX block is replaced atomically (leaf merge versus atomic replacement). GET the current block, edit it, and send the whole block back. Values under customTokens and palette, by contrast, deep-merge at the leaf.

Use the tokens the theme already defines

• Palette colors: the standard primary, secondary, error, warning, info, and success, plus the InStore-defined tertiary and the background.statusBar surface. You can set their values and add shades you reference, such as primary.dark.
• Typography: the standard variants (h1 to h6, body1, body2, caption, …) plus the InStore secondary-body variant.
• Scalars: shape.borderRadius, spacing, breakpoints, and zIndex are plain values you can set directly.

Find the identifier for any element

If a surface is not in the tables below, read its identifier straight from a running POS:

1. Open the POS in a desktop browser, right-click the element, and choose Inspect.
2. In the Elements panel, read the element's class list. It tells you the MUI component (.MuiButton-root to MuiButton), the slot (the -root, -paper, -elevation, ... suffix), any state class (Mui-disabled, Mui-selected), and the instore-* hook.
3. Look the instore-* hook up in the tables below, or target it directly with the layer-2 procedure.

Update a component style step by step

Work through the styling layers in order, applying only the ones you need. The layers are value tokens, component-level styles, and specific element styles. Each step names the exact JSON path so you know where the change goes.

1. GET the current theme and keep it. It is both your starting point and, because component blocks are replaced atomically, the block you will edit and resend. To review the endpoint response shape, see GET /theme.
2. Find the element's row in the component reference to get its MUI component, slot, and class.
3. Layer 1: get or choose the token (the value layer). Reuse a value the theme already defines, or set one under the relevant top-level group: palette for a color, shape.borderRadius for corners, spacing for gaps, zIndex for stacking, typography for text. The example below changes a color, but the same step applies to any token type. This edits palette.*, shape.*, spacing, zIndex.*, or typography.*.
4. Layer 2: set the component-level (global) style. Put properties that should apply to every instance of that MUI component in components.MuiX.styleOverrides.<slot>. This edits components.MuiX.styleOverrides.<slot>.
5. Layer 3: set the specific element's style. Target the one surface through its class, either a nested &.instore-Y selector inside the slot or a variants entry with a className matcher. This edits the &.instore-Y block (or components.MuiX.variants[]).
6. PATCH the full components.MuiX block (atomic replacement), reload the POS, and re-inspect. Prefer token references over hard-coded hex, and remember that numeric radius and spacing are theme multiples. If your rule is struck through in DevTools, it was overridden. To adjust selector specificity and rule order, see Ensure your change has precedence.

Example: recolor the primary action button

{
  "palette": {
    "tertiary": { "main": "#1B7E3F", "dark": "#176B36", "contrastText": "#ffffff" }
  }
}

{
  "props": { "className": "instore-primary-action" },
  "style": {
    "backgroundColor": "tertiary.main",
    "color": "tertiary.contrastText",
    "&:hover": { "backgroundColor": "tertiary.dark" }
  }
}

Example: restyle the cart line item

{
  "components": {
    "MuiPaper": {
      "styleOverrides": {
        "elevation": {
          "&.instore-line-item-card": {
            "backgroundColor": "background.paper",
            "borderRadius": "8px",
            "padding": "28px 20px",
            "& .instore-line-item-image": {
              "width": "140px",
              "minWidth": "140px",
              "height": "140px"
            }
          }
        }
      }
    }
  }
}

Ensure your change has precedence

Two rules can match one element; for each property only the rule with precedence applies. Make your rule more specific, or define it later, so it has precedence.

Why a change can be overridden

• Interaction states: a surface is often styled separately for &:hover, &:active, &.Mui-selected, &.Mui-disabled, and &.Mui-focusVisible. Change the base alone and the states keep their old look. Set the ones you care about too.
• Child elements re-scope a property: a parent often sets a color on its children by selector. For example, the sidebar button sets icon and label color with & .MuiListItemIcon-root and & .MuiListItemText-primary. Those children are also styled on their own components (MuiListItemIcon, MuiListItemText), so a color can live in two places.
• !important in the bundled theme: a few sizes are pinned with !important (the add-coupon and coupon-scan buttons) so a component sx cannot beat them. To override those, your value must use !important as well.
• More than one component or variant: the same look can come from several components (input focus borders) or from variants that override the base (the sidebar sub-item and the mobile footer item both re-set the button background).

Surfaces that need extra care for precedence

Worked example: recolor the sidebar menu button

{
  "components": {
    "MuiListItemButton": {
      "styleOverrides": {
        "root": {
          "backgroundColor": "primary.main",
          "color": "primary.contrastText",
          "& .MuiListItemIcon-root": { "color": "primary.contrastText" },
          "& .MuiListItemText-primary": { "color": "primary.contrastText" },
          "&:hover": { "backgroundColor": "primary.dark" },
          "&.Mui-selected": { "backgroundColor": "primary.dark" },
          "&.Mui-disabled": { "backgroundColor": "action.disabledBackground" }
        }
      }
    }
  }
}

Component class reference

• styleOverrides.<slot>, &.instore-x: a nested class selector inside a styleOverrides slot (most surfaces).
• variants (className): a className variant entry.
• & .instore-x (nested): a child element styled inside its parent's block; edit it there, not as a top-level component.

App frame

Sidebar (navigation drawer)

Search and scan

Cart page and layout

Cart line item

Cart totals (money box)

Dialogs

Global component overrides (no class hook)

Behavior and global settings

Example: hide the mobile footer menu

{
  "customTokens": { "layout": { "mobileFooter": false } }
}

Example: move the sidebar to the left

{
  "components": {
    "MuiDrawer": {
      "defaultProps": { "anchor": "left", "variant": "permanent" },
      "variants": [],
      "styleOverrides": { "paper": {} }
    }
  }
}

Related pages

• Customize POS styles and behavior: the guide for customizing POS styles with the layered override model and worked examples.
• Theme API reference: the GET, PUT, and PATCH endpoints, customTokens field reference, and validation rules.
• Overview: how theme configuration, MUI, and the InStore POS fit together.