Skip to content
oks-ui

Start here

oks-ui has dozens of components, and you do not need to read about all of them. This is a path through the library in the order most apps need it, with the page to open at each step.

1. Install and render one thing

Follow Installation: one package, one stylesheet import, no provider. When a Button shows up with its styles, you are set up. If you use TypeScript, every prop below is typed, and a wrong value is an error before you run anything (see TypeScript).

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

<Button color="primary" onPress={() => alert("It works")}>Hello</Button>

2. Learn the conventions once

The same few ideas repeat across every component, so learning them on a Button pays off everywhere.

  • Props describe state, not styling. color, size, variant and radius take the same values everywhere. State uses isDisabled, isOpen and isLoading.
  • Controlled or not, your choice. Most components take value with onChange, or defaultValue and keep it themselves.
  • Your own CSS has the last word. Every component accepts className and a classNames map for its parts, and its styles sit in a low-priority layer, so a plain class of yours wins.
  • Accessible names are your job. Where a component cannot invent one (a Table, a Nav, an icon-only button), it requires an aria-label and the types say so.

3. Build a form

Most apps start with a form. FormFieldSet renders every field type (text, select, switch, date and more) through one component, and Form collects the values and the errors.

<Form onSubmit={(data) => console.log(data)}>
  <FormFieldSet type="text" name="name" label="Name" />
  <FormFieldSet type="email" name="email" label="Email" validation={{ rules: { required: true, email: true } }} />
  <Button type="submit">Save</Button>
</Form>

Then read Compose a form for steps, errors and server-side checks.

4. Lay out a page

oks-ui gives you the pieces and leaves the page structure to you: Nav for the side menu, Card for grouped content, SplitLayout for resizable panes, Tabs for switching panels. The layout guide shows them together, and the patterns are whole pages you can copy.

5. Show data

Table handles sorting, selection and expanded rows; Pagination splits a long list into pages; and Chart draws line, bar, pie, heatmap and other charts as SVG, with no charting library. Show an EmptyState when there is nothing to show, and a Skeleton while it loads.

6. Give feedback

Tell people what happened. A Toast confirms a quick action, an Alert stays on the page until the problem is fixed, and a Modal asks before something that cannot be undone.

import { toast } from "oks-ui";

toast.success("Saved", { description: "Your changes were saved." });

Toast needs one ToastProvider near the root of your app; the Toast page shows where.

7. Make it yours

Colours, spacing, type and radii are CSS variables, so a brand is a few lines of CSS. Start with Theming, then dark mode. If your app speaks more than one language, see Translate and localize.

8. Keep going