Getting Started with oks-ui in React

oks-ui is a React component library written in strict TypeScript, styled with CSS variables, with no runtime dependencies besides React. This guide takes you from an empty React app to a themed page with working components in about five minutes.

1. Install

oks-ui works with React 18 or newer, in any bundler — Vite, Next.js, webpack or others. No build plugin is needed.

npm install oks-ui

2. Load the design tokens once

Colours, spacing, radii and type sizes are CSS custom properties. Import them once at the root of your app — in your main CSS file or your root layout:

@import "oks-ui/tokens.css";
@import "oks-ui/utilities.css";

utilities.css adds a small set of spacing and radius helper classes like oks-p-4 and oks-mt-2. It is optional.

3. Render a component

Import each component from its own entry point, with its stylesheet:

import { Button } from "oks-ui/button";
import "oks-ui/button.css";

export function App() {
  return (
    <Button color="primary" onPress={() => alert("Hello!")}>
      Say hello
    </Button>
  );
}

Per-component imports mean your app only ships the components it uses. You can also import everything from oks-ui and load oks-ui/styles.css — simpler, but larger.

4. Build something small

A card with a title, a form field and a button:

import { Card } from "oks-ui/card";
import "oks-ui/card.css";
import { PageTitle } from "oks-ui/page-title";
import "oks-ui/page-title.css";
import { FormFieldSet } from "oks-ui/form-field-set";
import "oks-ui/form-field-set.css";
import { Button } from "oks-ui/button";
import "oks-ui/button.css";

export function Newsletter() {
  const [email, setEmail] = useState("");
  return (
    <Card shadow="md" radius="lg" style={{ padding: 24, maxWidth: 420 }}>
      <PageTitle as="h2" title="Stay in the loop" subtitle="One email a month. No spam." />
      <FormFieldSet
        type="email"
        name="email"
        label="Email"
        value={email}
        onChange={(v) => setEmail(String(v ?? ""))}
      />
      <Button color="primary" fullWidth style={{ marginTop: 16 }}>
        Subscribe
      </Button>
    </Card>
  );
}

Form fields emit their value directly — onChange receives the new value, not a browser event.

5. Dark mode

Set data-theme="dark" on the html element and every component switches:

document.documentElement.setAttribute("data-theme", "dark");

There is no theme provider to wrap your app in. To avoid a flash of the light theme on page load, set the attribute in a small script in the document head before the page paints — the dark mode guide has the full snippet.

6. Your brand colour

Every colour comes from CSS variables, so theming is overriding a few of them. The brand theming guide walks through the primary colour ramp, corner radius and density.

Using Next.js?

oks-ui components use React state and effects. In the Next.js App Router, add "use client" at the top of files that render them. Pages are still prerendered to full HTML. With Turbopack, keep the .css import next to each component import, because Turbopack doesn't follow a stylesheet imported from inside a package.

Where to go next

• Browse all components with live examples and every prop.
• Copy complete screens from patterns: sign-in, dashboards, settings and more.
• Read the installation guide for more setup detail.