Getting started
Customization
Five ways to change a component, from the smallest change to the largest. Start at the top and move down only when the step above can't do what you need.
- 1 Override CSS variables Change the look everywhere
- 2 Pass a class Adjust one instance
- 3 Extend the variants Add a reusable style
- 4 Compose parts Change the markup
- 5 Copy the source Change how it works
1. Override CSS variables
Colours, radii, shadows and fonts are CSS variables. Set them in the app stylesheet after the theme import and every component follows. Theming covers the details and scoped overrides.
:root {
--radius-card: 20px;
--shadow-card: none;
}2. Pass a class
Every component takes a class prop. It goes through cn(), which
removes conflicting Tailwind classes. Your class comes last, so it wins.
<Button class="w-full">Restore website</Button>
<!-- size="sm" sets h-control-sm px-4. The class wins: -->
<Button size="sm" class="h-10 px-6">Renew domain</Button>cn is exported, so your own components can merge classes the same way:
import { cn } from '@statix/ui/utils';
cn('px-4 text-body text-ink', 'px-6 text-white');
// -> 'text-body px-6 text-white'
// px-6 replaces px-4, text-white replaces text-ink, text-body stays (it is a size)cn knows the Statix theme keys. Without that, it would read text-body as a colour and drop text-white. The keys are registered
in mergeConfig in packages/ui/src/lib/utils.ts. When you add a theme
key to the package that shares a prefix with a Tailwind utility (text-*, shadow-*, rounded-*, h-*), add it there as well:
// packages/ui/src/lib/utils.ts
const mergeConfig = {
extend: {
theme: {
text: ['display', 'section', 'heading', /* ... */ 'label', 'caption'],
radius: ['card'],
shadow: ['card', 'overlay', 'dock']
}
}
};Apps that define their own theme keys hit the same problem, because the package's cn doesn't know them. Give app keys a prefix Tailwind doesn't use, or propose the key
for the package.
3. Extend the variants
Components with variants export them: buttonVariants, badgeVariants and so on. Build on them with tv from @statix/ui/utils. It uses the same merge rules as cn.
import { tv } from '@statix/ui/utils';
import { buttonVariants } from '@statix/ui/button';
export const shopButton = tv({
extend: buttonVariants,
variants: {
variant: {
success: 'bg-success text-success-foreground hover:bg-success/90'
},
size: {
xl: 'h-14 px-8 text-lead'
}
}
});<script lang="ts">
import { Button } from '@statix/ui/button';
import { shopButton } from '$lib/variants';
</script>
<Button class={shopButton({ variant: 'success', size: 'xl' })}>Order now</Button>
<!-- Or style a plain element the same way -->
<a href="/checkout" class={shopButton({ variant: 'success' })}>Go to checkout</a>The shopButton classes come after the button's own classes, so bg-success replaces bg-primary. If a variant is useful in more than
one app, add it to the package instead.
4. Compose parts
Components built on bits-ui accept a child snippet. It replaces the rendered element
and hands you the props to spread, so a trigger can be any component:
<script lang="ts">
import { Button } from '@statix/ui/button';
import * as Dialog from '@statix/ui/dialog';
</script>
<Dialog.Root>
<Dialog.Trigger>
{#snippet child({ props })}
<Button {...props} variant="outline">Change password</Button>
{/snippet}
</Dialog.Trigger>
<Dialog.Content>...</Dialog.Content>
</Dialog.Root>When the package has no matching component, use bits-ui directly and style it with the Statix
utilities. Add bits-ui to the app's dependencies first.
<script lang="ts">
import { Popover } from 'bits-ui';
import { cn } from '@statix/ui/utils';
</script>
<Popover.Root>
<Popover.Trigger class="h-chip rounded-full bg-secondary px-3 text-label">DNS</Popover.Trigger>
<Popover.Content class={cn('rounded-lg bg-popover p-4 text-small shadow-overlay')}>
A record: 194.126.80.12
</Popover.Content>
</Popover.Root>5. Copy the source
As a last resort, copy the component into the app and edit it there. You stop getting fixes from package updates for that component, so note where it came from.
git clone git@gitlab.statix.dev:statix/web/design-system.git /tmp/design-system
mkdir -p src/lib/components/ui
cp -r /tmp/design-system/packages/ui/src/lib/components/button src/lib/components/ui/button
rm src/lib/components/ui/button/*.test.tsThen replace the package-internal imports:
// before (inside the package)
import { cn, tv, type VariantProps } from '#lib/utils.js';
// after (in your app)
import { cn, tv, type VariantProps } from '@statix/ui/utils';If you copied it because the package can't do something, open an issue in the design system project. A fix there helps every app.