Usage

For framework-specific setup (Vite, Next.js App Router, Remix), see Framework usage.

Importing components

Integrating Rad UI into your project is straightforward. Whether you're looking for a headless library with full flexibility or a quick way to prototype with a default theme, Rad UI has you covered. Here’s how you can get started.

To use Rad UI components, import them from per-component entrypoints:

React
import Button from "@radui/ui/Button";

See Barrel export policy for why root barrel imports are discouraged in application code.

Using components

Once you've imported the components you need, you can start using them right away. Here's an example of how to integrate Rad UI’s Button component into your app:

React
const ComponentDemo = () => {
    return (
        <Button>Click me</Button>
    )
}

We recommend wrapping Rad UI components with your own abstractions to streamline usage, customize behavior, and remove unnecessary features. See the Design system integration cookbook for recipes. This approach offers the flexibility to ensure consistency and maintainability across your project, while still taking full advantage of Rad UI’s powerful APIs. By abstracting components in this way, you can tailor them to fit your specific needs and provide your team with a consistent, centralized API. If your project already has a design system in place, you don't have to follow Rad UI's default API; you’re free to adapt it to align with your own system's requirements.

Importing base styles

Rad UI is headless by default. Components work without built-in visual styles, so you can bring your own design system, utility classes, CSS Modules, SCSS, or any other styling approach. Read Styling and customization for supported hooks and what to avoid overriding.

For how theme tokens and fallback values work, see CSS variable fallbacks.

If you want Rad UI's default design system styles, import the default theme stylesheet explicitly:

React
import "@radui/ui/themes/default.css";

If you prefer to use your own styles, you do not need to import any Rad UI CSS. Alternatively, you can import only the styles you need by referring to the specific component’s documentation page.

Theme

Rad UI provides a Theme component that sets shared visual context for a subtree. Use it to configure things like appearance and accent color, and to opt into generated component classes when you want to target Rad UI's default styles or your own namespaced design system CSS.

Basic usage

You can configure global settings such as appearance and accent color to align with your product or design system:

React
import Theme from "@radui/ui/Theme";

const App = () => {
    return (
        <Theme appearance="dark" accentColor="gray">
            <YourApp />
        </Theme>
    )
}

This keeps visual preferences in one place and makes them easy to apply consistently across your app.

Using classNamespace

By default, Theme does not add generated component classes on its own.

This means the following stays classless from the library's point of view:

React
<Theme>
    <Accordion.Root />
</Theme>

If you want generated classes for a subtree, pass classNamespace:

React
<Theme classNamespace="rad-ui">
    <Accordion.Root />
</Theme>

This generates namespaced classes such as:

html
<div class="rad-ui-accordion-root"></div>

Use classNamespace when:

  • you want to use Rad UI's default theme stylesheet
  • you want to namespace your own design system CSS
  • you want a stable class contract for styling component parts

If you are importing the default Rad UI CSS, wrap that subtree with Theme classNamespace="rad-ui" so the generated class names match the selectors in the stylesheet:

React
import "@radui/ui/themes/default.css";
import Theme from "@radui/ui/Theme";

const App = () => {
    return (
        <Theme classNamespace="rad-ui" appearance="dark" accentColor="gray">
            <YourApp />
        </Theme>
    )
}

If you are bringing your own styles, choose any namespace that fits your system:

React
<Theme classNamespace="acme">
    <Accordion.Root />
</Theme>

This generates classes like acme-accordion-root, acme-accordion-item, and acme-accordion-trigger.

For the full Theme API, see the dedicated Theme component docs.

Tailwind presets

Rad UI provides first-class support for Tailwind CSS, allowing you to easily integrate Rad UI's design system tokens into your Tailwind setup. By importing the appropriate preset, you gain access to a wide range of design tokens, making it seamless to build and customize your UI.

For Tailwind CSS v4

Import the preset as CSS, after Tailwind itself, in your global stylesheet:

css
/* globals.css */
@import "tailwindcss";
@import "@radui/ui/themes/tailwind-presets/default.css";

That exposes the Rad UI colour ramps as Tailwind utilities:

React
<div className="bg-gray-100 text-gray-1000 border-gray-300" />

Every value resolves through a --rad-ui-* custom property defined by the Rad UI theme CSS, so switching themes — including dark mode — re-resolves the utilities without a rebuild. Opacity modifiers such as bg-gray-500/90 are composed by Tailwind itself and work as usual.

Note that the preset covers colours only. Spacing, radius, shadow, blur and typography utilities keep Tailwind's own defaults, so your existing utilities are unchanged.

Prior versions

The v4 preset replaces the JavaScript preset that shipped for Tailwind CSS v3, which was imported through presets in tailwind.config.js. If you are still on v3, upgrade Tailwind before upgrading Rad UI — the v3 preset has been removed.

Edit this page on GitHub →