Skip to content
DocsStyle
Style

Appearance settings

Theme, density, light direction, key travel, motion and text direction can all change while the app runs. This page explains how these settings work and how to use them from your own code.

#The settings

Each setting is an attribute on the <html> element. CSS reads the attribute, and the page changes. No component needs to know about it.

Setting Attribute on <html> Values What changes
Theme data-am-theme light (default), graphite, system Every color and shadow. system follows the operating system's light or dark mode.
Density data-am-density comfortable (default), compact Smaller gaps and padding. Table rows go from 56px to 44px and lose their fill.
Light source data-am-light top-left (default), top-right Every shadow flips to the other side.
Key travel data-am-keycap travel (default), flat Keys keep their edge but stop moving down when pressed.
Motion data-am-motion full (default), reduced Stops all entrances, drawing, counting and loops.
Direction dir ltr (default), rtl The layout flips for right-to-left languages.
Language lang en (default) The language used to format numbers and dates.

Three rules make the system simple:

  1. The default writes nothing. When a setting has its default value, there is no attribute on <html> and nothing is saved. The default look is the plain CSS in _roles.css.
  2. Every choice is saved in localStorage, under a key that starts with am:, such as am:theme. The choice is still there after a reload.
  3. No flash on load. A small script at the top of index.html reads the saved choices and sets the attributes before the page is drawn. A graphite reload never shows a light frame first.

#The Appearance drawer

The drawer on the right lets users change every setting except the language. It opens from:

  • the cog key at the bottom of the sidebar (on wide screens), and
  • Appearance in the avatar menu.

Reset returns every setting to its default and removes the saved choices.

The code is in src/components/shell/Customizer.tsx. Each row in its ROWS list is one setting. Remove a row to hide that setting from users.

#Use the settings in your code

src/lib/theme.ts has a small API:

TypeScript
import { get, set, reset, onChange, resolvedMode } from '@/lib/theme';

set('mode', 'graphite');     // switch to graphite and save it
set('density', 'compact');
get('mode');                  // the saved choice: 'light', 'graphite' or 'system'
resolvedMode();               // what is showing now: 'light' or 'graphite'
reset();                      // every setting back to its default

const stop = onChange(() => {
  // runs after any setting changes
});
stop(); // stop listening

The setting names are mode (the theme), density, light, keycap, motion, dir and lang.

Every change also fires an am:change event on window, so code outside React can listen too.

Inside React, use the useCustomizer() hook. It gives you the current values and re-renders when they change:

TSX
import { useCustomizer } from '@/context/customizer';

function ThemeKey(): React.JSX.Element {
  const { values, setAxis } = useCustomizer();
  const dark = values.mode === 'graphite';

  return (
    <Button on={dark} onClick={() => setAxis('mode', dark ? 'light' : 'graphite')}>
      Dark theme
    </Button>
  );
}

#Right-to-left layout

Set Direction to RTL and the whole layout mirrors: the sidebar moves to the right, and text, icons and gaps flip. The styles use CSS logical properties (margin-inline-start instead of margin-left), so no extra style sheet is needed.

When you write your own styles, use logical properties too:

Instead of Use
margin-left, padding-right margin-inline-start, padding-inline-end
left: 0 inset-inline-start: 0
text-align: left text-align: start
Tailwind ml-4, pr-2 Tailwind ms-4, pe-2

Icons that point in a direction, such as arrows, need the class am-flip-rtl to turn around in RTL.

Charts always draw from left to right, as charts do in most right-to-left languages. Their tooltips follow the page direction.

#Language and number formats

The lang attribute decides how src/lib/format.ts writes numbers, currency and dates. With en, the template uses US English formats.

To format for another language, add its code to the lang setting's values in src/lib/theme.ts, then call set('lang', 'de-DE'). Every formatter then uses German formats, for example 1.240,5.

The template's own words (titles, labels and messages) are written in English inside the page files. To translate the interface, use a library such as react-i18next and replace the text in the pages with translation keys.

#Remove the Appearance drawer

The drawer is part of the demo. You may not want your users to change the look. To remove it:

  1. Delete src/components/shell/Customizer.tsx.
  2. In src/components/shell/index.ts, delete the line that exports Customizer.
  3. In src/components/shell/Shells.tsx, delete the Customizer import and the two <Customizer ... /> elements. You can also delete the customizer, openCustomizer and closeCustomizer parts of useChrome.
  4. In src/components/shell/Keypad.tsx, delete the cog key (the button with the label "Appearance settings") and the Appearance item in the avatar menu, and remove the onOpenCustomizer prop.
  5. Run npm run check to find anything left over.

Keep CustomizerProvider in App.tsx and the files in src/context/. Three design kit pages (surfaces, tables and motion) use them for their live switches. The settings themselves keep working, and saved choices still apply.