Skip to main content
Get your first Soft UI component running in minutes. This guide walks you through installation, setup, and your first interactive component.
1

Install packages

Install the core Soft UI packages using your preferred package manager:
npm install @soft-ui/tokens @soft-ui/icons @soft-ui/react
2

Import styles

Import the Soft UI styles once in your app entry point (e.g., app/layout.tsx or _app.tsx):
import "@soft-ui/tokens/styles.css"
3

Configure Tailwind v4

Add Soft UI’s component source scanning to your CSS file (e.g., app/globals.css):
@import "@soft-ui/tokens/styles.css";
@source "../node_modules/@soft-ui/react/dist/**/*.{js,mjs}";
This ensures Tailwind v4 scans Soft UI components for utility classes.
4

Initialize theme (optional)

For theme switching support, add the theme initialization script to your root layout:
app/layout.tsx
import { createThemeInitScript } from "@soft-ui/tokens"

export default function RootLayout({ children }) {
  return (
    <html suppressHydrationWarning>
      <head>
        <script
          dangerouslySetInnerHTML={{
            __html: createThemeInitScript(),
          }}
        />
      </head>
      <body>{children}</body>
    </html>
  )
}
This prevents flash of unstyled content (FOUC) and syncs with system preferences.
5

Use your first component

Import and use the Button component via subpath imports:
app/page.tsx
import { Button } from "@soft-ui/react/button"

export default function Home() {
  return (
    <div>
      <Button variant="primary">Click me</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="tertiary">Tertiary</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="danger">Delete</Button>
    </div>
  )
}
All components support variants, sizes, and design tokens out of the box:
<Button variant="primary" size="l">
  Large Button
</Button>
<Button variant="secondary" size="s">
  Small Button
</Button>

​
Next steps

Components

Explore all available UI components

Design Tokens

Customize colors, spacing, and typography

Installation Guide

Advanced setup and configuration

API Reference

Component props and variants