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:
-
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. -
Every choice is saved in
localStorage, under a key that starts witham:, such asam:theme. The choice is still there after a reload. -
No flash on load. A small script at the top of
index.htmlreads 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:
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:
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:
- Delete
src/components/shell/Customizer.tsx. -
In
src/components/shell/index.ts, delete the line that exportsCustomizer. -
In
src/components/shell/Shells.tsx, delete theCustomizerimport and the two<Customizer ... />elements. You can also delete thecustomizer,openCustomizerandcloseCustomizerparts ofuseChrome. -
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 theonOpenCustomizerprop. - Run
npm run checkto 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.