`. The key `card("hover")` applies `text-blue-600` while the `

` is hovered. Write the variants inside the call, such as `card("hover:active")`, to combine states. The label `"card"` is optional and only helps you read the generated class names. The compiler creates a unique name for each `style.ref()` call, so two components can use the label `"card"` without affecting each other. ## React to a sibling's state Without `.in()`, the ref must be on an ancestor of the styled element. To use a sibling, add `.in()` with a ref on an element that contains both: ```tsx import { style } from "stillwind/react"; const card = style.ref("card"); const trigger = style.ref("trigger"); export function Card() { return (

This text changes color while the button is hovered.

); } ``` `trigger("hover").in(card)` matches while the `

Anchor-positioned content

); } ``` `style.anchorScope([trigger])` limits the anchor name to the `

`, so each rendered `AnchoredHint` positions against its own button. Stillwind generates CSS anchor positioning only. Check that the browsers you support implement it. ## Share refs between components Export a ref from its module and import it where you need it. Keep the call or `.in()` chain, such as `card("hover")`, directly in the key of the `style()` call. You cannot store it in a variable and use it later. ## Report group and peer variants The `stylistic` preset includes [prefer-typed-relationships](/docs/lints/prefer-typed-relationships). The rule reports `group-*` and `peer-*` variants so that you can replace them with refs. The [style.ref() reference](/docs/macros/ref) lists every method and its accepted inputs. # Checks in the editor and CI > Catch misspelled utilities, conflicts, and project policy violations with the CLI, CI, and the editor. Source: https://stillwind.dev/docs/guides/lint-adoption · Markdown: https://stillwind.dev/docs/guides/lint-adoption/index.md You want to catch misspelled utilities, conflicting styles, and values outside your theme before you merge a change. Stillwind checks them with lint rules. The CLI, CI, the editor, and AI agents all use the same rules from `stillwind.config.ts`. ## What the build checks The build stops on compiler errors, such as a JavaScript syntax error or a `style()` call that cannot compile. See [Compiler errors](/docs/errors). The build does not run lint rules. A misspelled utility such as `bg-acent` produces no CSS, and the page still renders without that style. Run the CLI or use the editor to find such mistakes. ## Run the CLI ```sh vp i -D @stillwind/cli ``` Run these commands from the application root: ```sh vp exec stillwind lint vp exec stillwind lint --fix vp exec stillwind fmt ``` `lint` reports findings. `lint --fix` also applies the automatic fixes that the rules provide. `fmt` sorts the utilities in `style()` calls. Review the changes before you commit a large fix. The CLI checks the files that `files` selects in `stillwind.config.ts`, including files that the application does not import. ## Choose rules Without a `lint` setting, the project uses the `recommended` preset. Add a `lint` setting to add presets or change rules: ```ts title="stillwind.config.ts" import { defineConfig, lintPresets } from "stillwind/config"; export default defineConfig({ projects: [ { css: "./src/stillwind.css", files: ["src/**/*.{ts,tsx,vue,svelte,astro}"], lint: { extends: [lintPresets.recommended, lintPresets.stylistic], rules: { "no-arbitrary-colors": "warn" }, }, }, ], }); ``` When you write a `lint` setting, list `lintPresets.recommended` in `extends`. A `lint` setting without `extends` uses no preset. | Preset | Contents | | ------------- | ---------------------------------------------------------------------- | | `recommended` | Invalid input, conflicting styles, and other likely mistakes | | `strict` | Every `recommended` rule as an error, and unused suppression comments | | `stylistic` | Preferred spellings and utility sorting; combine it with `recommended` | Each rule has a severity. `warn` reports a warning, `deny` reports an error, and `off` disables the rule and its fixes. To adopt a new rule, set it to `warn` first, fix the existing code, and then change it to `deny`. [Configuration](/docs/configuration#lint) describes rule options, and the [lint rule reference](/docs/lints) lists every rule. ## Run the checks in CI ```sh vp exec stillwind lint vp exec stillwind fmt --check ``` `lint` fails when an error remains. `fmt --check` fails when utilities need sorting. Warnings do not fail the command. Add `--max-warnings 0` to fail on warnings too. In GitHub Actions, the CLI prints findings as annotations that link to the reported lines. ## Let AI agents run the checks Tell your agent to run `stillwind lint --fix` and `stillwind fmt` after it edits styles. The agent sees the same findings as you. Add `--format json` when the agent or a script reads the results. ## Check while you edit The VS Code extension shows findings as you type, including in unsaved files. It also offers the automatic fixes as Quick Fixes, and it can fix and sort on save. See [Editors](/docs/editors) for the setup. ## Allow an exception When code breaks a rule on purpose, add a comment on the line above it. Name the rule, and give the reason after `--`: ```ts import { style } from "stillwind/react"; // swlint-disable-next-line no-arbitrary-colors -- External brand color. export const badge = style("bg-[#123456]"); ``` A comment hides the finding only. It does not make a misspelled utility produce CSS, and it does not hide compiler errors. # Migrating from CSS > Move styles from plain CSS, CSS Modules, preprocessors, or CSS-in-JS into style() calls and theme tokens. Source: https://stillwind.dev/docs/guides/migrating-from-css · Markdown: https://stillwind.dev/docs/guides/migrating-from-css/index.md You want to move a project that styles elements with plain CSS, CSS Modules, Sass, Less, or CSS-in-JS to Stillwind. Unlike a migration from Tailwind CSS, you translate declarations into utilities. Check the pages in the browser after each step, because the translation can change how elements look. ## Set up Stillwind next to the existing CSS Install Stillwind and register the build integration as described in [Getting started](/docs). Your existing stylesheets keep working while you migrate. `@import "stillwind"` includes the preflight reset, which changes the default styles of elements such as headings and lists. To migrate in steps, leave out the reset until the old styles are gone: ```css @layer properties, theme, base, components, utilities; @import "stillwind/theme.css" layer(theme); @import "stillwind/utilities.css" layer(utilities); @import "stillwind/builtins.css"; @import "stillwind/templates.css"; ``` [Stylesheets](/docs/concepts/stylesheets) describes each of these files. Stillwind's CSS is in cascade layers. A declaration outside a layer wins over a declaration in a layer, whatever their specificity. While an old rule matches an element, it overrides the utilities on that element. Remove the old rule when you move its declarations. ## Move values into the theme Collect the colors, spacing, font sizes, radii, and breakpoints that the old CSS repeats, such as Sass variables or custom properties in `:root`. Define them as `@theme` tokens by role: ```css @theme { --color-surface: oklch(0.98 0 0); --color-accent: oklch(0.6 0.2 250); --breakpoint-tablet: 48rem; } ``` Each token adds utilities, such as `bg-surface` and `tablet:`. Merge values that mean the same thing. Keep values separate when they are equal by chance. [Design systems](/docs/guides/design-systems) describes how to name tokens. ## Move rules into style() Translate the declarations of each rule into utilities, and apply them with `style()` on the element: ```css title="Button.module.css" .button { padding: 0.5rem 1rem; border-radius: 0.375rem; background: var(--accent); } .button:hover { opacity: 0.9; } .button[disabled] { cursor: wait; } ``` ```tsx import { style } from "stillwind/react"; export function Button({ loading }: { loading: boolean }) { return ( ); } ``` Translate selectors into variants: | Old CSS | Stillwind | | -------------------------------------- | ---------------------------------------------------------------------- | | `:hover`, `:focus-visible`, `:checked` | `hover:`, `focus-visible:`, `checked:` | | `@media (min-width: 768px)` | A breakpoint variant, such as `md:` | | `[aria-expanded="true"]`, `[data-x]` | `aria-expanded:`, `data-[x]:` | | `.parent:hover .child` | A ref, see [Element relationships](/docs/guides/element-relationships) | | A toggled modifier class | An attribute and its variant | | A value set from JavaScript | A custom property in `style()` | A declaration without a matching utility can use an arbitrary property, such as `[content-visibility:auto]`. When several elements need it, define a custom utility instead. ## Replace global rules - Keep resets and base element styles until you enable the preflight reset. Then remove the rules that it replaces. - Move `@keyframes` next to the component that uses them with [style.keyframes()](/docs/macros/keyframes). - Move styles for HTML that you do not control, such as rendered Markdown, into a custom utility. See [Recommended practices](/docs/guides/recommended-practices#avoid-separate-css). ## Replace CSS-in-JS Move static styles from `styled()` components or `css` props into `style()` calls. Express props that change styles with attributes and variants, as in [Reusable styles](/docs/guides/reusable-styles). For a continuous value, set a custom property in `style()`. ## Check the migrated code Run the [CLI checks](/docs/guides/lint-adoption) over the migrated files, and compare the pages with the old version in the browser. After you remove the last old stylesheet, switch to `@import "stillwind"` and check the pages again. # Migrating from Tailwind CSS > Move a Tailwind CSS v4 project to Stillwind, from the stylesheet and build to components and configuration. Source: https://stillwind.dev/docs/guides/migrating-from-tailwind · Markdown: https://stillwind.dev/docs/guides/migrating-from-tailwind/index.md You want to move an existing Tailwind CSS v4 project to Stillwind. Your utilities, variants, theme, and plugins keep working. What changes is where you write them: in `style()` calls instead of `className` strings. [Tailwind CSS compatibility](/docs/guides/tailwind-compatibility) lists the tested plugins and the differences. Tailwind scans your files for anything that looks like a class name. Stillwind generates CSS only for the utilities in `style()` calls. A class in a plain `className` string, or in HTML from another source, gets no CSS after the migration. Move every utility that you want to keep into `style()`. ## Replace the stylesheet and the build plugin In your stylesheet, replace `@import "tailwindcss"` with `@import "stillwind"`: ```css @import "stillwind"; @theme { --color-brand: oklch(0.6 0.2 250); } ``` Keep your `@theme`, `@utility`, `@custom-variant`, `@variant`, `@apply`, and `@plugin` rules. Replace the Tailwind build plugin, such as `@tailwindcss/vite`, with the Stillwind integration. Then create `stillwind.config.ts`, as described in [Getting started](/docs#configure-the-project), and set up your framework, as described in [Framework integrations](/docs/integrations). ## Move classes into style() Replace each `className` string with a `style()` call that you spread onto the element: ```tsx import { style } from "stillwind/react"; export function Button() { return ; } ``` Import `style` from the entrypoint of the framework that renders the element. For a class that another stylesheet defines, pass it in a `class` field, such as `style("p-4", { class: "external-card" })`. A large codebase may have hundreds of `className` strings. Your coding agent can write a one-off codemod for your repository that converts them in one pass. ## Replace class helpers `style()` and `style.cva()` replace the libraries that Tailwind projects use to build class strings: | Library | Stillwind | | ----------------------------------- | ----------------------------------------- | | `clsx`, `classnames` | `style()` with conditions | | `tailwind-merge` | Compose a base with new utilities | | `cva` from class-variance-authority | `style.cva()` with the same configuration | ### clsx and classnames Pass conditions as arguments: ```tsx import { style } from "stillwind/react"; export function SaveButton({ loading }: { loading: boolean }) { return ( ); } ``` Do not convert the object form of `clsx`. In `clsx({ "opacity-60": loading })`, each key is a class name. In `style()`, each key of an object is a variant, such as `"hover:"`. Rewrite each entry as `loading && "opacity-60"`. ### tailwind-merge Remove `twMerge()` calls. Store the base style and pass it to another `style()` call. The compiler emits the new utilities after the base's CSS. They override competing declarations when the other cascade criteria, such as specificity and importance, are equal. See [Override a style](/docs/guides/style#override-a-style) and [CSS ordering](/docs/concepts/css-ordering). ### cva Replace `cva(` with `style.cva(`, and import `VariantProps` from your framework's entrypoint: ```tsx import { style, type VariantProps } from "stillwind/react"; const button = style.cva("rounded-md px-4 py-2", { variants: { tone: { neutral: "bg-gray-100", primary: "bg-brand text-white", }, }, defaultVariants: { tone: "neutral", }, }); export function Button({ tone }: VariantProps) { return ; } ``` `variants`, `defaultVariants`, and `compoundVariants` work as in class-variance-authority. Write each option value as a plain utility string, without `&&` or a ternary. The props that the factory returns cannot be passed to `style()` as a base. The [style.cva() reference](/docs/macros/cva) lists the other differences. For new components, consider state variants and `data-*` attributes instead of options. See [Reusable styles](/docs/guides/reusable-styles). ## Move configuration Some Tailwind settings move from the stylesheet to `stillwind.config.ts`: | Tailwind | Stillwind | | --------------------------------- | -------------------------------------------- | | `@config "./tailwind.config.js"` | The `tailwind` field of the project | | `@import "tailwindcss" important` | The `important` field of the project | | `@source` and `source(...)` | Not supported; see below | | `blocklist` | The `no-restricted-utilities` lint rule | | `prefix(tw)` | Write utilities without `tw:`; see below | | `theme(...)` on the import | Not supported; define the tokens in `@theme` | The `tailwind` field accepts a Tailwind configuration object. Its `theme`, `presets`, `plugins`, `darkMode`, and `important` keys work as in Tailwind. Other keys have no effect. This field requires the `tailwindcss` package. Set `important` in one place only. Setting both `important` and `tailwind.important` is an error. Stillwind does not need the `tw:` class prefix, because it generates unique class names. Theme variables can still collide with other CSS in the page. To keep the `--tw-` names of `prefix(tw)`, set `themePrefix: "--tw-"` on the project. The prefix applies to the generated CSS, including `var(--color-brand)` in your stylesheet and in arbitrary values, so you can keep `var(--tw-color-brand)` or use the shorter name. JavaScript that reads or sets a theme variable by name must use the prefixed name. Stillwind does not support `@source`, including `@source inline()`, or a safelist, because only `style()` calls generate utilities. Tailwind classes inside a dependency also get no CSS. Write each utility that you need in a `style()` call in your own code. Stillwind ignores `@config`, `@source`, `@reference`, and import options in the stylesheet, and the CLI reports them with [ignored-tailwind-feature](/docs/lints/ignored-tailwind-feature). Remove them after you move their settings. The same rule reports a v3 path in `theme()`, such as `theme(colors.red.500)`. Use `--theme(--color-red-500)` instead. Keep your `@plugin` rules and the `@import` rules of CSS packages. [Tailwind CSS compatibility](/docs/guides/tailwind-compatibility#plugins-and-css-packages) lists the packages that the test suite covers. ## Check the migrated code Run the [CLI checks](/docs/guides/lint-adoption) over the migrated files. They report utilities that Stillwind cannot resolve and Tailwind features that it ignores. Then test the production build and your pages in the browser. # Recommended practices > Keep styles next to their elements, reuse them through components, and avoid the mistakes that produce no CSS. Source: https://stillwind.dev/docs/guides/recommended-practices · Markdown: https://stillwind.dev/docs/guides/recommended-practices/index.md This page collects the practices that keep a Stillwind project easy to change. It also lists the mistakes that silently produce no CSS. The examples use React. ## Keep styles next to their elements Write the utilities in a `style()` call on the element that they style. When several places need the same styles, reuse them in this order: 1. Extract a component of your framework, and keep the `style()` call on its element. The styles stay next to the markup that they depend on. 2. Define a custom utility in your stylesheet when a component does not fit, such as for links inside other components' text. A utility is available in every file of the project, so its effect is wider than a component's. 3. Export a stored `style()` result. The styles then move away from the element that uses them. When you use an imported style, spread it through `style()`: ```tsx import { style } from "stillwind/react"; import { card } from "./card"; export function Panel() { return

…

; } ``` `{...style(card)}` shows that the element receives Stillwind styles, and you can add utilities in the same call. A plain `{...card}` hides this. ## Spread style() onto the element Spread the result of `style()` onto the element. Do not read `className`, `class`, or `style` out of the result. The result can contain more than one prop, and its shape depends on the framework and on the inputs. If code needs a class string for another purpose, that code does not need `style()`, and a migration can leave it unchanged. Set custom properties in the `style()` call, such as `style("w-(--progress)", { "--progress": value })`. `style()` returns a `style` prop when it needs inline values, so a separate `style` prop on the same element can conflict with it. Set the `style` prop directly only on elements without a `style()` call. You can also use `style()` for an element that has custom properties and no utilities. ## Express states with attributes Keep the same classes on an element, and let its attributes decide which styles apply: - For a state with an attribute, such as `disabled` or `aria-pressed`, use the matching variant. - For an option without a matching attribute, set a `data-*` attribute and use a `data-[…]:` variant. - For a value from a continuous range, set a custom property in the `style()` call, and read it in a utility such as `w-(--progress)`. Use a condition such as `selected && "bg-blue-50"` only when no attribute fits. [Reusable styles](/docs/guides/reusable-styles) shows each approach. Do not track in JavaScript a state that CSS can detect, such as hover, focus, or the width of a container. Use the matching variant, and keep component state for what the application needs. ## Connect elements with refs When an element's style depends on another element, such as a hovered parent, a sibling, a container, or an anchor, connect them with a ref from `style.ref()`. Do not use `group-*`, `peer-*`, named containers, or hand-written parent and sibling selectors: ```tsx import { style } from "stillwind/react"; export function Card() { const card = style.ref("card"); return (

Project

); } ``` A ref is a variable, so TypeScript reports a misspelled ref, and two components cannot collide on the same name. Anchors for anchor positioning use refs too. [Element relationships](/docs/guides/element-relationships) covers siblings, containers, and anchors. ## Define animations in their components Define keyframes with [style.keyframes()](/docs/macros/keyframes) and view transitions with [style.viewTransition()](/docs/macros/view-transition) in the code that uses them. Do not add global `@keyframes` rules or fixed `view-transition-name` values. The macros generate unique names, so you can add, move, or remove a component without checking other code. ## Declare refs and animations in the smallest scope Declare a ref, keyframes, or a view transition in the smallest scope that contains all of its uses, as you would declare any other variable. Place the declaration next to those uses: - A declaration that one component uses belongs in that component's function. - A declaration that a callback uses, such as a `map()` callback, belongs in that callback. - A declaration that several components of one module use belongs at the top level of that module. - When other modules use a declaration, export it from one module, and import it where you need it. Each declaration creates one name wherever you write it. A smaller scope limits where the variable is visible, and it does not create a new name for each render or call. ## Express options with one of a fixed set of values For a prop that takes one of several values, such as a `type` or a `tone`, use one of these forms. Set the value as a `data-*` attribute, and write one variant group for each value: ```tsx import { style } from "stillwind/react"; export function Alert({ type }: { type: "info" | "warning" | "error" }) { return (

); } ``` Or select the utilities with an object lookup: ```tsx import { style } from "stillwind/react"; export function Alert({ type }: { type: "info" | "warning" | "error" }) { return (

); } ``` The attribute form keeps the classes static and changes a `data-*` attribute. The attribute also shows the value in the browser's developer tools and in test queries. The lookup form changes the classes and adds no attribute. In both forms, each value has its utilities in one place. The two forms produce different CSS: - The attribute form compiles into one class. The element always has this class, and the attribute selectors decide which declarations apply. - The lookup form generates one class for each value. The lookup selects one of these classes at runtime. In this example, the common styles add one more class, which the element always has. In both forms, the styles for a value usually win over the common styles. In the attribute form, the attribute selector adds specificity, and the variant order places the rules after the common styles. In the lookup form, the compiler places the utilities that a condition selects after the unconditional utilities. More specific selectors and `!important` can still change the result. [CSS ordering](/docs/concepts/css-ordering) describes these rules. ## Group utilities by variant When several utilities share a variant, group them under one key instead of repeating the prefix: ```tsx style({ "": "rounded-md bg-gray-100 px-4 py-2", "hover:": "bg-gray-200 text-gray-900", "focus-visible:": "outline-2 outline-offset-2 outline-accent", }); // Or write the base utilities as a separate string. style("rounded-md bg-gray-100 px-4 py-2", { "hover:": "bg-gray-200 text-gray-900", "focus-visible:": "outline-2 outline-offset-2 outline-accent", }); ``` The key `""` groups utilities without adding a variant. Each group shows the styles of one state, so readers do not need to collect the prefixed utilities from a long string. > **The key "" accepts the same inputs as a variant** > > The value of `""` accepts only the inputs that a variant group accepts. Write ref attachments, > `class` values, custom properties, and bases directly in the `style()` arguments, outside the > object. Otherwise the CLI reports > [invalid-rule-group-input](/docs/lints/invalid-rule-group-input), and the compiler omits the whole > group. Ref projections, keyframes uses, and view-transition uses can appear in the group. ## Keep values in the theme Define colors, spacing, and breakpoints as `@theme` tokens, and use the utilities that they add. Avoid arbitrary values such as `text-[#abcdef]` and `max-[768px]:`. [Design systems](/docs/guides/design-systems) enables lint rules that report them. ## Choose how to define themes When the application has only a light and a dark theme, define each color token with `light-dark()`, and let `color-scheme` select the value. [Design systems](/docs/guides/design-systems) shows this setup. When the application can have more themes, `light-dark()` cannot express them. Define the tokens as ordinary values, and override them for each theme with an attribute selector. Set `color-scheme` in each theme, so that form controls and scroll bars match: ```css @theme { --color-surface: #ffffff; --color-foreground: #202b45; } [data-theme="dark"] { color-scheme: dark; --color-surface: #1b263b; --color-foreground: #e4edff; } [data-theme="sepia"] { color-scheme: light; --color-surface: #f4ecd8; --color-foreground: #433422; } ``` Set `data-theme` on the root element, or on a container to theme part of the page. The utilities, such as `bg-surface`, stay the same in every theme. When a theme needs styles beyond its tokens, define a variant for it with [@custom-variant](/docs/at-rules/custom-variant), and use the variant instead of a hand-written selector: ```css @custom-variant theme-sepia (&:where([data-theme="sepia"], [data-theme="sepia"] *)); ``` ## Use breakpoints from the theme in JavaScript When JavaScript needs a breakpoint, get its media query with [style.media()](/docs/macros/media) instead of repeating the value: ```ts import { style } from "stillwind/react"; const sidebar = window.matchMedia(style.media("sidebar")); ``` A query such as `matchMedia("(width >= 52.5rem)")` does not follow a later change of the breakpoint in the theme. Prefer a variant when CSS alone can make the change. [Responsive styles](/docs/guides/responsive-styles) shows more uses. ## Define utilities with @apply Write the body of a custom utility with `@apply`, and write its conditions as variants: ```css @utility link { @apply text-accent underline-offset-4 hover:underline; } ``` Do not write selectors or media queries by hand. The variants follow your theme, and they avoid differences that are easy to miss. For example, the `hover:` variant applies only on devices that can hover, while a plain `:hover` rule stays active after a tap on a touch screen. Inside a style rule, use [@variant](/docs/at-rules/variant) instead of a condition. ## Avoid separate CSS Write styles in `style()` calls and custom utilities, not in CSS files with your own class names. A custom utility works with every variant, such as `hover:link`, and a fixed class name does not. For a reusable condition, define a variant with [@custom-variant](/docs/at-rules/custom-variant) instead of writing its selector in several rules. For HTML that you do not control, such as rendered Markdown, define the styles in a custom utility and apply it to the container. You can also use a Tailwind plugin such as `@tailwindcss/typography`. ## Run the checks after each change Run `stillwind lint --fix` and `stillwind fmt` after you change styles, and fix the remaining findings. Add a suppression comment only for a deliberate exception, and give the reason. See [Checks in the editor and CI](/docs/guides/lint-adoption). ## Mistakes that produce no CSS The build succeeds in each of these cases, but the styles do not apply. Run `stillwind lint` to find most of them. - A class name outside `style()`, such as in a `className` string, gets no CSS. - A utility name that your code builds at runtime, such as `` `bg-${color}-600` ``, gets no CSS. Write complete names, such as `color === "red" ? "bg-red-600" : "bg-blue-600"`. - A `style()` call written directly inside another `style()` call contributes nothing. Store the inner style in a variable first. - Custom properties in a base do not carry over to the styles that extend it. Set them in the `style()` call that is spread onto the element. - Classes in the `class` field pass through without generated CSS. - A suppression comment hides a finding only. A misspelled utility still produces no CSS. The compiler can evaluate the arguments of `style()` in any order, and it can skip arguments whose result is not used. Calculate values and perform effects before you call `style()`. # Responsive styles > Name breakpoints once, and use them in utilities, authored CSS, and JavaScript. Source: https://stillwind.dev/docs/guides/responsive-styles · Markdown: https://stillwind.dev/docs/guides/responsive-styles/index.md You want components to change layout at the same widths. Tailwind defines breakpoints in CSS, so a JavaScript check such as `matchMedia("(width >= 52.5rem)")` repeats the value. In Stillwind, you name each breakpoint once and use the name in both CSS and JavaScript. ## Name breakpoints by layout role Name breakpoints after the layout change that they cause, instead of a device size: ```css @import "stillwind"; @theme { --breakpoint-inline: 40rem; --breakpoint-sidebar: 52.5rem; --breakpoint-outline: 70rem; } .navigation { @apply flex flex-col gap-3; @variant inline { @apply flex-row; } } ``` Each `--breakpoint-*` token adds a variant, such as `sidebar:`. The default breakpoints, such as `md:`, remain available unless you remove them. ## Use breakpoints in components ```tsx import { style } from "stillwind/react"; export function Layout() { return (

Content

); } ``` ## Use breakpoints in authored CSS In a CSS rule, nest `@variant` with the breakpoint name, as in the `.navigation` rule above. In an `@utility` definition, use the variant in `@apply` instead, such as `@apply inline:flex-row`. ## Use breakpoints in JavaScript `style.media()` returns the media query for a breakpoint name: ```ts import { style } from "stillwind/react"; const sidebar = window.matchMedia(style.media("sidebar")); const update = () => { document.documentElement.dataset.sidebar = String(sidebar.matches); }; sidebar.addEventListener("change", update); update(); export function dispose() { sidebar.removeEventListener("change", update); } ``` The compiler replaces `style.media("sidebar")` with the query string, so the JavaScript always matches the CSS. `matchMedia()` is a browser API, so call it on the client. Remove the listener when its component unmounts. To combine conditions, write them in one argument. To accept alternatives, pass several arguments: ```ts import { style } from "stillwind/react"; const enhanced = window.matchMedia(style.media("outline:motion-safe", "print")); ``` This query matches a viewport at least as wide as `outline` without a reduced-motion preference, or a printed page. `style.media()` accepts media conditions only. Element states such as `hover` are not media conditions. ## Report widths outside your breakpoints The [no-arbitrary-breakpoints](/docs/lints/no-arbitrary-breakpoints) rule reports widths written as values, such as `min-[713px]:`. See [Design systems](/docs/guides/design-systems#report-values-outside-the-theme) to enable it. To respond to the width of a component instead of the viewport, use a container query. See [Element relationships](/docs/guides/element-relationships#react-to-a-containers-size). # Reusable styles > Share a base style, and express states and options with variants instead of toggled classes. Source: https://stillwind.dev/docs/guides/reusable-styles · Markdown: https://stillwind.dev/docs/guides/reusable-styles/index.md You want components to share styles and to change their look by state or by option. In Stillwind, you share a base style, and you express states and options with variants. The element keeps the same classes, and its attributes decide which styles apply. ## Share a base style Store a `style()` result, and pass it to other `style()` calls. You can export the base and import it in other modules: ```tsx import { style } from "stillwind/react"; export const button = style( "inline-flex rounded-md bg-gray-100 px-4 py-2 font-medium text-gray-900", ); const primaryButton = style(button, "bg-blue-600 text-white"); const dangerButton = style(button, "bg-red-600 text-white"); export function Actions() { return (

); } ``` In this example, the derived styles replace the base's background and text colors. Their CSS comes after the base's CSS, and their selectors have equal specificity. The order of the class names does not affect the result. A base's `hover:` selector can be more specific than a plain class in the derived style. [CSS ordering](/docs/concepts/css-ordering) explains variants, conditions, and multiple bases. A base passes on its classes only. Custom properties such as `{ "--progress": value }` in the base do not carry over, and the CLI reports them. Set custom properties in the `style()` call that is spread onto the element. ## Express states with variants Set the state as an attribute, and style it with a variant: ```tsx import { style } from "stillwind/react"; export function ToggleButton({ pressed }: { pressed: boolean }) { return ( ); } ``` The `aria-pressed` attribute is needed for accessibility anyway. Use variants such as `disabled:`, `aria-expanded:`, and `open:` in the same way. The element always has the same classes, so you do not need to think about which toggled class wins. ## Express options with data attributes For an option without a matching ARIA attribute, set a `data-*` attribute: ```tsx import { style } from "stillwind/react"; export function Badge({ tone, label }: { tone: "neutral" | "danger"; label: string }) { return ( {label} ); } ``` The attribute also shows the option in the browser's developer tools and in test queries. For a value from a continuous range, such as a width or a progress percentage, set a custom property instead. See [Use runtime values](/docs/guides/style#use-runtime-values). ## Migrate CVA components `style.cva()` accepts the configuration of `cva` from class-variance-authority. Use it to migrate existing CVA components. See [Replace class helpers](/docs/guides/migrating-from-tailwind#replace-class-helpers) and the [style.cva() reference](/docs/macros/cva). # The basics of style() > Apply utilities, variants, conditions, overrides, and runtime values to an element. Source: https://stillwind.dev/docs/guides/style · Markdown: https://stillwind.dev/docs/guides/style/index.md `style()` takes Tailwind CSS v4 utilities and returns props for an element. You spread the props onto the element instead of writing a `className` string. This page uses React. For other frameworks, import `style` from the entrypoint listed in [Framework integrations](/docs/integrations). ## Apply utilities ```tsx import { style } from "stillwind/react"; export function Workspace() { return (

Your workspace

Keep your component styles together.

); } ``` The compiler reads the utilities at build time and generates their CSS. In React, `style()` returns a `className` prop. Utilities and variants come from the stylesheet that `stillwind.config.ts` selects. A token that you add to `@theme` adds utilities, such as `bg-accent` for `--color-accent`. ## Add variants Write variants as in Tailwind: ```tsx import { style } from "stillwind/react"; export function SaveButton() { return ( ); } ``` To apply several utilities under the same variant, use an object. Each key is a variant followed by a colon: ```tsx import { style } from "stillwind/react"; export function Link() { return ( Documentation ); } ``` ## Style states When the element has an attribute for the state, use a variant: ```tsx import { style } from "stillwind/react"; export function SaveButton({ loading }: { loading: boolean }) { return ( ); } ``` The element keeps the same classes, and the browser applies the `disabled:` styles while the button is disabled. [Reusable styles](/docs/guides/reusable-styles) shows the same approach with `aria-*` and `data-*` attributes. When no attribute represents the state, pass a condition and a string, as with `clsx`: ```tsx import { style } from "stillwind/react"; export function Row({ selected }: { selected: boolean }) { return

Inbox

; } ``` The compiler generates CSS for both strings. At runtime, the condition decides whether the element gets `bg-blue-50 font-medium`. Write complete utility names in the source. The compiler cannot generate CSS for a name that your code builds at runtime, such as `` `bg-${color}-600` ``. Choose between complete names instead, such as `color === "red" ? "bg-red-600" : "bg-blue-600"`. ## Override a style Store a `style()` result in a variable, and pass it to another `style()` call. The compiler places CSS for the new utilities after the base's CSS: ```tsx import { style } from "stillwind/react"; const button = style("rounded-md bg-blue-600 px-4 py-2 text-white"); const dangerButton = style(button, "bg-red-600"); export function DeleteButton() { return ; } ``` In this example, `dangerButton` has a red background because both background rules use equally specific selectors. The order of the class names does not affect the result. You can export a stored style and use it in other modules. More specific selectors and `!important` can change which declaration wins. See [CSS ordering](/docs/concepts/css-ordering) for variants, conditions, and multiple bases. Store the inner style in a variable first. A `style()` call written directly inside another, such as `style(style("p-4"), "text-sm")`, is not supported. [Reusable styles](/docs/guides/reusable-styles) covers shared styles and component options in more detail. ## Use runtime values For a value that is known only at runtime, set a CSS custom property and read it in a utility: ```tsx import { style } from "stillwind/react"; export function Progress({ value }: { value: number }) { return (

); } ``` The utility `w-(--progress)` stays the same, so its CSS is generated at build time. Only the value of `--progress` changes at runtime. ## Add classes from other stylesheets To add a class that another stylesheet defines, pass it in a `class` field: ```tsx import { style } from "stillwind/react"; export function Card({ className }: { className?: string }) { return

; } ``` Stillwind passes these classes through and does not generate CSS for them. ## Keep arguments free of side effects The compiler can evaluate the arguments of `style()` in any order, and it can skip arguments whose result is not used. Calculate values and perform effects, such as state updates or I/O, before you call `style()`. ## Next steps - [Reusable styles](/docs/guides/reusable-styles): how to share styles and define component options - [Responsive styles](/docs/guides/responsive-styles): how to name breakpoints and use them in JavaScript - [Checks in the editor and CI](/docs/guides/lint-adoption): how to find misspelled utilities and other mistakes - [The style() reference](/docs/macros/style): every accepted input # Tailwind CSS compatibility > Check which Tailwind CSS v4 features, plugins, and CSS packages work in Stillwind, and what Stillwind does differently by design. Source: https://stillwind.dev/docs/guides/tailwind-compatibility · Markdown: https://stillwind.dev/docs/guides/tailwind-compatibility/index.md Stillwind supports the utilities, variants, theme, CSS directives, and plugins of Tailwind CSS v4. To move a project, follow [Migrating from Tailwind CSS](/docs/guides/migrating-from-tailwind). This page lists what works, how Stillwind checks it, and where Stillwind differs. ## What works | Tailwind feature | Support | | --------------------------------------- | -------------------------------------------------------------------- | | Default theme and preflight | Included in `@import "stillwind"` | | Utilities and variants | Supported, including arbitrary values, modifiers, and `!` | | `@theme`, `@utility`, `@custom-variant` | Supported | | `@apply`, `@variant` | Supported | | `--theme()`, `--spacing()`, `--alpha()` | Supported | | `theme(--color-red-500)` | Supported; v3 paths such as `theme(colors.red.500)` are not | | `@plugin` with JavaScript plugins | Supported; see [Plugins and CSS packages](#plugins-and-css-packages) | | `@import` of CSS packages | Supported; see [Plugins and CSS packages](#plugins-and-css-packages) | | Tailwind configuration | Set the `tailwind` field of the project in `stillwind.config.ts` | ## How Stillwind checks compatibility The test suite compares Stillwind with the Tailwind compiler. It runs both compilers on the same input and fails when their results differ: - For utilities and variants, it compares the generated CSS for each class in Tailwind's public class list and in its variant list. - For plugins and CSS packages, it builds the same stylesheet with both compilers and compares the computed styles in Chrome. The declarations inside a rule can stand in a different order from Tailwind's, as [CSS ordering](/docs/concepts/css-ordering) describes. The order of two declarations that can affect each other stays the same, so the computed styles do not change. ## Plugins and CSS packages Tailwind CSS v4 plugins work in Stillwind in principle. The test suite runs the following packages in Vite development and production builds and in Rspack production builds. It also compares their output with Tailwind. Load these packages with `@plugin`: | Package | Example | | ----------------------------------- | ------------------------------------------- | | `@tailwindcss/typography` | `prose`, `prose-lg`, `prose-headings:` | | `@tailwindcss/forms` | `form-input`, and the base styles of forms | | `daisyui` | `btn`, `card`, `badge`, themes | | `tailwindcss-animate` | `animate-in`, `fade-in-50` | | `tailwindcss-motion` | `motion-preset-fade`, `motion-duration-700` | | `tailwind-scrollbar` | `scrollbar-thin`, `scrollbar-thumb-brand` | | `tailwindcss-radix` | `radix-state-open:` | | `tailwindcss-react-aria-components` | `selected:` | | `@headlessui/tailwindcss` | `ui-open:` | | `@iconify/tailwind4` | `icon-[lucide--home]` | For Iconify icons, Stillwind also provides the [`@stillwind/plugin-iconify`](/docs/plugins/iconify) plugin. Load these packages with `@import`: | Package | Example | | ---------------------------- | -------------------------------------- | | `tw-animate-css` | `animate-in`, `fade-in-50` | | `tailwindcss-animated` | `animate-fade`, `animate-duration-700` | | `tailwindcss-intersect` | `intersect:` | | `tailwindcss-safe-area` | `pt-safe-or-4` | | `tailwind-scrollbar-hide/v4` | `scrollbar-hide` | | `preline/variants.css` | `hs-dropdown-open:` | Other plugins can use the same features. [@plugin](/docs/at-rules/plugin#tailwind-css-plugins) lists the supported plugin API. JavaScript plugins need the `tailwindcss` package, and CSS packages do not. The tests cover CSS. They do not run the JavaScript of a package, such as the components of Preline. Plugins have no browser test with webpack or Next.js. Test these combinations in your application. ### Class names that a plugin's selectors use A plugin can select an element by a fixed class name. For example, the rules of `prose` skip elements inside `not-prose`. `style()` keeps such a class in the `class` attribute, so `style("not-prose")` adds the class `not-prose`. The class keeps its name only without variants, so [invalid-marker-use](/docs/lints/invalid-marker-use) reports `hover:not-prose`. ## What Stillwind does not support These differences come from the design of Stillwind. No setting changes them. ### Classes outside style() Only `style()` calls generate utilities. Stillwind does not scan files, so these features have no replacement: - `@source`, `@source inline()`, and `source(...)` on `@import` - A safelist of class names - Tailwind classes inside a dependency - Utility classes that JavaScript adds at runtime, such as `` `bg-${color}-600` `` Write each utility that you need in a `style()` call in your own code. For HTML that you do not control, see [Avoid separate CSS](/docs/guides/recommended-practices#avoid-separate-css). ### The tw: class prefix Stillwind generates unique class names, so utilities do not need a prefix. Write `p-4` instead of `tw:p-4`. Theme variables can still collide with other CSS in the page. To prefix them, set `themePrefix` on the project, as [Migrating from Tailwind CSS](/docs/guides/migrating-from-tailwind#move-configuration) describes. In a plugin, `prefix()` returns the class name unchanged. ### Other differences | Tailwind | Stillwind | | ------------------------------------------ | --------------------------------------------------------------------------------- | | `@reference` | Ignored; `@import` the stylesheet from the stylesheet of the project | | `theme(colors.red.500)` | Stays in the CSS, where browsers reject it; use `--theme(--color-red-500)` | | `blocklist` | Has no effect; use the `no-restricted-utilities` lint rule | | Utilities that generate invalid CSS | Rejected, such as `justify-baseline`, because `justify-content` has no such value | | `addVariant()` with the v3 `:merge()` form | Skipped, as in Tailwind CSS v4 | [ignored-tailwind-feature](/docs/lints/ignored-tailwind-feature) reports the features in your stylesheet that have no effect. # View transitions > Style view transition snapshots in the component, and give each item a stable name. Source: https://stillwind.dev/docs/guides/view-transitions · Markdown: https://stillwind.dev/docs/guides/view-transitions/index.md You want an item to animate between two states of the page with the browser's View Transition API. In plain CSS, you write `view-transition-name` and the `::view-transition-*` rules in a global stylesheet, and you keep every name unique by hand. In Stillwind, you define the transition in the component and name each item with a key. ## Define the transition and name each item ```tsx import { style } from "stillwind/react"; const productTransition = style.viewTransition({ old: "duration-150 motion-reduce:duration-0", new: "delay-150 duration-150 motion-reduce:delay-0 motion-reduce:duration-0", }); export function Product({ id, name }: { id: string; name: string }) { return

{name}

; } ``` `style.viewTransition()` defines the styles of the snapshots. Each field styles one pseudo-element: | Field | Pseudo-element | | ----------- | -------------------------------- | | `group` | `::view-transition-group()` | | `imagePair` | `::view-transition-image-pair()` | | `old` | `::view-transition-old()` | | `new` | `::view-transition-new()` | Timing utilities in these fields set animation properties. For example, `duration-150` sets `animation-duration`. `.for(id)` gives the element a view transition name from the key. Use a key that stays the same for the same item before and after the update, such as a database ID. Two items on the page at the same time need different keys. ## Start the transition Stillwind generates the styles and names. Your code starts the transition: ```ts export function navigate(update: () => void) { if (document.startViewTransition) { document.startViewTransition(update); } else { update(); } } ``` Call `update` the way your framework normally renders a change. Browsers without the View Transition API run the update without animation. ## Give each element one name Use `.for()` once for each element, in one `style()` call. To combine several transitions on one element, pass the others without `.for()`: ```tsx import { style } from "stillwind/react"; const fade = style.viewTransition({ old: "duration-150" }); const slide = style.viewTransition({ new: "duration-300" }); export function Card({ id }: { id: string }) { return

Card

; } ``` The CLI reports a `style()` call that applies a transition without `.for()`, a call with two `.for()` calls, and transitions split across separate `style()` calls. It cannot check that keys are unique across the whole page. The [style.viewTransition() reference](/docs/macros/view-transition) covers dynamic keys and the generated CSS. # Web Components > Add the compiled styles of a component module to its shadow root. Source: https://stillwind.dev/docs/guides/web-components · Markdown: https://stillwind.dev/docs/guides/web-components/index.md You want to style the elements inside the shadow root of a Web Component. The build integration adds compiled CSS to the page's stylesheet, but the page's stylesheet does not reach into a shadow root. Import the compiled CSS of the component's module from `stillwind/module-css`, and add it to the shadow root. ## Keep the styles out of the page ```ts title="vite.config.ts" import { stillwind } from "@stillwind/integration/vite"; import { defineConfig } from "vite"; export default defineConfig({ plugins: [ stillwind({ automatic: false, }), ], }); ``` With `automatic: false`, modules do not add their styles to the page's stylesheet. Each component adds its styles to its own shadow root instead. The webpack and Rspack plugins accept the same option. Keep the default when the application also styles elements outside shadow roots. A module that imports `stillwind/module-css` never adds its styles to the page. With the default, a module that only exports shared styles still adds them to the page. ## Import the CSS of a module ```ts import { css, parts } from "stillwind/module-css"; ``` The compiler replaces this import in each module that contains it. The CSS contains the styles of the `style()` calls in that module and the styles that those calls compose from other modules. It also contains the theme values, the preflight reset, and the other rules of your stylesheet. The import provides the CSS in two forms: - `css` is one string. Use it with an API that accepts stylesheet text, such as Lit's `static styles`. The default export is the same string. - `parts` lists the pieces of the CSS in order. Pass it to `styleSheets()` from `stillwind/css`, which returns constructed stylesheets. Shadow roots in the same document share the stylesheets for equal pieces, such as the preflight reset. ## Add the CSS to the shadow root Add the CSS where your framework sets up the shadow root. ### Lit ```ts import { html, LitElement, unsafeCSS } from "lit"; import { applyStyle, style } from "stillwind/lit"; import { css } from "stillwind/module-css"; class SaveButton extends LitElement { static styles = unsafeCSS(css); render() { return html``; } } customElements.define("save-button", SaveButton); ``` ### Vue Export `styles` from a plain ` ``` ```ts import { defineCustomElement } from "vue"; import SaveButton from "./SaveButton.ce.vue"; customElements.define("save-button", defineCustomElement(SaveButton)); ``` ### Svelte Set `compilerOptions.customElement` to `true` in `svelte.config.js`. Then adopt the stylesheets after the component mounts: ```svelte ``` ### Solid With `solid-element`, adopt the stylesheets in the component function: ```tsx import { customElement } from "solid-element"; import { styleSheets } from "stillwind/css"; import { parts } from "stillwind/module-css"; import { style } from "stillwind/solid"; customElement("save-button", {}, (_props, { element }) => { const root = element.renderRoot as ShadowRoot; root.adoptedStyleSheets = styleSheets(parts, element.ownerDocument); return ; }); ``` ### Vanilla JavaScript ```ts import { styleSheets } from "stillwind/css"; import { parts } from "stillwind/module-css"; import { applyStyle, clearStyle, style } from "stillwind/vanilla"; class SaveButton extends HTMLElement { readonly #root = this.attachShadow({ mode: "open", }); readonly #button = document.createElement("button"); constructor() { super(); this.#button.textContent = "Save"; this.#root.append(this.#button); } connectedCallback(): void { this.#root.adoptedStyleSheets = styleSheets(parts, this.ownerDocument); applyStyle(this.#button, style("px-4 py-2")); } disconnectedCallback(): void { clearStyle(this.#button); } } customElements.define("save-button", SaveButton); ``` ## Compile a stylesheet for a few utilities `style.css()` compiles the utilities that you pass into a CSS string. Use it for a small stylesheet, such as styles for `:host`, when you do not need the preflight reset or the other rules of your stylesheet: ```ts import { style } from "stillwind/vanilla"; export const hostCss = style.css("block p-4", { selector: ":host", }); ``` The `selector` option chooses the element that the utilities style. The string contains the theme values and keyframes that its utilities need, and it adds nothing to the page's stylesheet. Add it to the shadow root in the same way as the `css` string from `stillwind/module-css`, or create a stylesheet from it with `CSSStyleSheet.replaceSync()`. The [style.css() reference](/docs/macros/css) describes variants that choose their own element and the `template` option. ## Constraints - The CSS of a module contains only the styles of that module and the styles that it composes from other modules. The `style()` calls of a component in another module belong to the CSS of that module, even when the component renders into the same shadow root. Keep the `style()` calls for one shadow root in the module that imports the CSS, or compose styles from other modules into those calls. - Shadow roots share the stylesheets that `styleSheets()` returns. Do not change them: a change appears in every shadow root that adopts the same stylesheet. - If a browser that you support lacks `adoptedStyleSheets`, add `css` in a `