# Customize the InStore POS UI

Customize the visual style and layout behavior of the InStore POS with tenant-level theme configuration.

## How POS UI customization works

The InStore POS uses a theme to control visual decisions such as colors, typography, spacing, component styles, and layout behavior. You store the theme as JSON with the InStore Theming API. The POS fetches the stored theme when it loads and applies it across the POS application.

The theme follows the MUI theme structure and includes InStore-specific fields for POS layout behavior. You can update the theme without changing application code, but you should treat the theme payload as implementation configuration and keep your own backup of each applied payload.

## What you can customize

You can customize the following areas:

- Color palette and semantic color tokens.
- Typography, spacing, shape, and breakpoints.
- MUI component defaults, slot styles, and variants.
- POS-specific surfaces that expose `instore-*` class hooks.
- Responsive layout settings such as header visibility, footer visibility, and sidebar behavior.

Due to its hosted nature, the InStore POS supports only the theming strategies, fields, and components described in this documentation. Do not add custom theme tokens, components, variants, or other non-standard theming strategies. Non-standard theming is at risk of being overwritten by updates of the InStore POS.

For the complete list of theme fields, see [Theme payload fields](/instore/customization/pos-theme-api.md#theme-payload-fields). To map a visible POS surface to the theme path that controls it, see the [POS style reference](/instore/customization/pos-style-reference.md).

## Theme application model

The InStore POS ships with a bundled default theme. A tenant theme stored through the Theming API overlays that default theme. Values you set in the tenant theme apply; values you omit fall back to the bundled default. A `components.MuiX` block is handled differently from most fields: when you send a component block, the whole block is replaced.

```mermaid
flowchart LR
 Default[Bundled default theme<br/>ships with the app]
 Tenant[Your tenant theme<br/>configured via the Theming API]
 Merge{{deep-merge}}
 Applied[Applied theme]
 UI[Rendered InStore POS UI]
 Default --> Merge
 Tenant --> Merge
 Merge --> Applied --> UI
 classDef src fill:#C2C2FF,stroke:#6359FF,stroke-width:2px,color:#191741;
 classDef src2 fill:#9FF7EE,stroke:#08A88A,stroke-width:2px,color:#003037;
 classDef proc fill:#FFE7A8,stroke:#FFC738,stroke-width:2px,color:#191741;
 classDef out fill:#8F8FFF,stroke:#4E4ED7,stroke-width:2px,color:#191741;
 classDef fin fill:#F9C9C0,stroke:#FF8A00,stroke-width:2px,color:#191741;
 class Default src;
 class Tenant src2;
 class Merge proc;
 class Applied out;
 class UI fin;
```

Changes take effect the next time the POS loads. The Theming API stores only the active theme for a tenant, so keep your own version history of request and response payloads.

## Next steps

Use the following resources to continue customizing the InStore POS UI:

- [Run InStore POS API requests](/instore/customization/pos-api-access.md) to set the API host, Project, and tenant, get an access token, and send requests to InStore POS APIs.
- [Theme API reference](/instore/customization/pos-theme-api.md) to review the GET, PUT, and PATCH theme endpoints, request examples, response behavior, and validation rules.
- [Customize styles and behavior](/instore/customization/pos-theming.md) to create and update a theme with palette tokens, MUI component overrides, responsive layout tokens, and POS style hooks.
- [POS style reference](/instore/customization/pos-style-reference.md) to map POS surfaces to their class hooks, MUI components, slots, and behavior settings.

For general MUI concepts, see the [MUI theming guide](https://v7.mui.com/material-ui/customization/theming/).

## Related pages

- [Area overview page with navigation](/instore.md)
- [Next page: Run InStore POS API requests](/instore/customization/pos-api-access.md)
- [Search documentation and API specs](/search.md)