Theming
Colors, border radii, spacing, font sizes and shadows of every component come from CSS variables (prefixed with --ns-) defined in @ns/theme. Customizing the theme means changing the values of these variables; the component library doesn't need to be rebuilt.
Dark Theme
Add data-theme="dark" to <html> to switch to the dark theme. Remove it or set it to light to go back:
// Switch to dark
document.documentElement.setAttribute('data-theme', 'dark')
// Switch back to light
document.documentElement.setAttribute('data-theme', 'light')
Adding class="dark" to <html> works the same way.
The three cases in order of priority:
data-theme="dark"(orclass="dark") is set: dark;data-theme="light"is set: light, even if the system is in dark mode;- Neither is set: follow the system's dark mode setting (
prefers-color-scheme).
So if your project doesn't support the dark theme, set data-theme="light" on <html> explicitly. Otherwise the page turns dark automatically when the user's system is in dark mode.
The theme prop of NsConfigProvider is equivalent to setting data-theme on <html> and applies to the whole page. When theme isn't passed, it leaves the page theme alone.
data-theme can also be set on a container in the page so that only that part is dark:
<div data-theme="dark">
<!-- Components in here are dark -->
</div>
Overlays (Select dropdowns, Tooltip, Modal and so on) are mounted under body, outside the container, so they aren't affected by the container's data-theme and keep following the root element's theme.
Palettes
Six palettes are built in. Switch between them with data-palette on <html> (or on a container). Palettes can be combined with the dark theme. Use the palette button on the right of this site's top bar to preview every component in each palette.
data-palette | Style | Primary |
|---|---|---|
| Not set | Default | #1890ff |
classic | Classic | #409eff |
cyberpunk | Tech | #0094b8 |
luxury | Calm gold | #b8860b |
nature | Fresh green | #10b981 |
minimal | Minimal indigo | #6366f1 |
jade | Jade | #18a058 |
jade is green-based and its success color equals the primary color. In the dark theme its primary color is mint #63e2b7. Text on solid buttons is always white, which isn't clear enough on such a light primary color in the dark theme; the dark versions of nature and cyberpunk have the same issue.
document.documentElement.setAttribute('data-palette', 'nature')
// Back to the default palette
document.documentElement.removeAttribute('data-palette')
Custom Variables
Override the variables in your own styles, imported after @ns/ui/style.css:
:root {
--ns-color-primary: #7c3aed;
--ns-color-primary-light: #8b5cf6; /* hover */
--ns-color-primary-dark: #6d28d9; /* pressed */
--ns-color-primary-bg: #f5f3ff; /* light background in the light theme */
--ns-border-radius: 4px;
}
/* Light background in the dark theme: cover all three ways of enabling it */
:root.dark,
[data-theme='dark'] {
--ns-color-primary-bg: rgba(124, 58, 237, 0.2);
}
@media (prefers-color-scheme: dark) {
:root:not([data-theme='light']) {
--ns-color-primary-bg: rgba(124, 58, 237, 0.2);
}
}
A -bg set on :root has the same specificity as the dark theme selectors and comes later, so it still applies in the dark theme, where a light background on a dark page is glaring. That's why it is set again for the dark theme above. In the dark theme, any -bg and -bg-hover you haven't set are computed from the current color (the color at 20% and 30% opacity), so if you only change the color and not -bg, you can leave out the last two blocks.
To change only one page or area, use that container as the selector and add the ns-theme-scope class to the container:
<div class="report-page ns-theme-scope">…</div>
.report-page {
--ns-color-primary: #0f766e;
--ns-color-primary-light: #3f918b;
--ns-color-primary-dark: #0c5e58;
--ns-color-primary-bg: #e7f1f0;
}
The light color scale (--ns-color-primary-light-3 … -light-9) is computed on the element that declares it, from the primary color at that point; child elements inherit the computed result. Only when the container has the ns-theme-scope class is the scale recomputed on the container from the new primary color. The fixed variants -light, -dark and -bg have to be written yourself as above.
To set dark-theme values separately, the selectors must cover all three ways of enabling it: :root.dark, [data-theme='dark'], and :root:not([data-theme='light']) inside @media (prefers-color-scheme: dark). See the first example above.
Variables
Below are the commonly used variables. See packages/theme/src/variables.scss for the full list and dark.scss for the dark theme values.
Colors
Every color has the same set of suffixes. primary can be replaced with success, warning, danger, info or help.
| Variable | Usage |
|---|---|
--ns-color-primary | Primary color |
--ns-color-primary-light, -lighter | One and two steps lighter, often used for hover |
--ns-color-primary-dark, -darker | One and two steps darker, often used for pressed |
--ns-color-primary-bg, -bg-hover | Light background and its hover color, used by alerts and tags |
--ns-color-primary-light-3, -5, -7, -8, -9 | Light scale; larger numbers are lighter. Mixed from the primary and background colors, so they follow changes of color, palette and theme |
There are also --ns-color-white, --ns-color-black and --ns-color-transparent.
Text, Background, Border
| Variable | Usage |
|---|---|
--ns-text-color | Body text |
--ns-text-color-secondary | Secondary text |
--ns-text-color-tertiary | Hints |
--ns-text-color-disabled | Disabled text |
--ns-text-color-placeholder | Placeholder text |
--ns-bg-color | Background of components and the page |
--ns-bg-color-secondary, -tertiary | One and two steps darker, for table headers, stripes and such |
--ns-bg-color-page | Page background (the layer outside the content area) |
--ns-bg-color-hover, -active | Translucent overlay on hover and press |
--ns-bg-color-disabled | Disabled background |
--ns-fill-color, -light, -dark | Fill: slider and progress tracks, skeletons and such |
--ns-mask-color | Mask behind dialogs and drawers |
--ns-border-color | Border |
--ns-border-color-light, -lighter | Lighter borders and dividers |
--ns-border-color-hover | Border of input controls on hover |
Radius, Spacing, Size
| Variable | Value |
|---|---|
--ns-border-radius-sm / --ns-border-radius / -lg / -xl | 2px / 6px / 8px / 12px |
--ns-border-radius-round / -circle | 9999px / 50% |
--ns-spacing-1 … --ns-spacing-12 | From 4px, 4px per step (--ns-spacing-4 is 16px) |
--ns-size-xs / -sm / -md / -lg / -xl | 24px / 32px / 40px / 48px / 56px |
--ns-component-size-large / --ns-component-size / --ns-component-size-small | 40px / 32px / 24px (control height incl. border) |
Typography
| Variable | Value |
|---|---|
--ns-font-family, --ns-font-family-mono | Body font, monospace font |
--ns-font-size-xs / -sm / -base / -lg / -xl | 12px / 14px / 14px / 16px / 20px |
--ns-font-size-2xl … -5xl | 24px / 30px / 38px / 48px |
--ns-line-height-tight / -normal / -relaxed / -loose | 1.25 / 1.5 / 1.75 / 2 |
--ns-font-weight-normal / -medium / -semibold / -bold | 400 / 500 / 600 / 700 |
Shadow, Transition
| Variable | Usage |
|---|---|
--ns-shadow-sm, --ns-shadow, -md, -lg, -xl, -2xl | Shadows, light to strong |
--ns-transition-duration-fast / -normal / -slow | 150ms / 200ms / 300ms |
--ns-transition-timing-function | Timing function |
The z-index of component overlays (dialogs, drawers, dropdowns, tooltips and so on) isn't controlled by CSS variables. It starts at 2000 and is written in each overlay's inline style. The theme's --ns-z-index-* (1000–1080) are only for utility classes such as ns-z-dropdown and ns-z-modal; changing them doesn't affect component overlays.
Utility Classes
The theme includes a set of utility classes prefixed with ns- that can be used on elements in your pages:
| Category | Examples |
|---|---|
| Text | ns-text-left, ns-text-center, ns-text-primary, ns-text-secondary, ns-ellipsis, ns-ellipsis-2 |
| Background | ns-bg-primary, ns-bg-primary-light, ns-bg-secondary |
| Layout | ns-flex, ns-flex-col, ns-items-center, ns-justify-between, ns-gap-2 |
| Radius, shadow, border | ns-rounded, ns-rounded-lg, ns-shadow, ns-shadow-md, ns-border |
| Other | ns-hidden, ns-cursor-pointer, ns-overflow-auto, ns-w-full |
See packages/theme/src/base.scss for the full list.
Using the Mixins in Your Own SCSS
@ns/theme also provides SCSS mixins (breakpoints, text truncation, scrollbars, flex layout and more). Projects using SCSS can import them:
@use '@ns/theme/scss/mixins.scss' as ns;
.title {
@include ns.text-ellipsis(2);
}
.sidebar {
// Breakpoints: sm 640px, md 768px, lg 1024px, xl 1280px, 2xl 1536px
@include ns.breakpoint-down('md') {
display: none;
}
}
Import only mixins. Don't @use '@ns/theme' as a whole in component styles; that outputs all the variables and reset styles again.