---
title: "Quickstart"
description: "Wrap your app in CladdProvider and compose the minimum app shell — the canonical layout cladd is designed around."
links:
doc: https://cladd.io/react/foundations/quickstart/
---
# Quickstart
This page is the shortest path from `npm install` to a cladd app that actually looks like a cladd app. It assumes you've completed the [Installation](/react/installation/) (the npm package, the Tailwind CSS import) and want to know what the _first_ layout you build should look like.
cladd is dense, surface-based, and dark by default. The minimum app is three pieces: a [`CladdProvider`](/react/components/cladd-provider/) at the root, an app shell composed from [`Surface`](/react/components/surface/) panels, and content laid into those surfaces using [`Toolbar`](/react/components/toolbar/), [`List`](/react/components/list/), and the rest of the kit.
## Wrap your app
[`CladdProvider`](/react/components/cladd-provider/) is the single root provider. It publishes the theme and the app-wide accent color, sets the overlays root, and mounts the dialog / toast portals that [`useDialog`](/react/hooks/use-dialog/) and [`useToast`](/react/hooks/use-toast/) push into. Wrap your tree once, at the top, and forget about it:
```tsx
import { CladdProvider } from '@cladd-ui/react';
export default function App({ children }) {
return (
{children}
);
}
```
Both `theme` and `accentColor` have sensible defaults (`'dark'`, `'brand'`), so a bare `{children}` is also fine. Switching the actual color tokens — toggling `` between dark and light palettes — is your app's responsibility; `theme` only tells cladd's floating surfaces (Popover, Dialog, Tooltip) which set of defaults to pick.
## A minimum app shell
The canonical cladd layout is a three-region shell: a [`Toolbar`](/react/components/toolbar/) running across the top, a [`List`](/react/components/list/) sidebar on the left, and a content [`Surface`](/react/components/surface/) on the right. Every region is a real cladd primitive — not a `
` styled to mimic one.
```tsx
import {
CladdProvider,
Surface,
Toolbar,
ToolbarButton,
ToolbarSeparator,
List,
ListButton,
ListTitle,
Chip,
Button,
} from '@cladd-ui/react';
export default function App() {
return (
{/* Left rail — workspace navigation. A floating Surface inset
with m-2 rounded-3xl is the cladd sidebar pattern; every
region sits as a rounded panel on the page bg, never
edge-to-edge. */}
Workspace12}>
Inbox
DraftsArchive
{/* Top bar — two Toolbars sharing one row. ml-auto on the
second pushes it to the right edge; contextual actions on
the left, chrome actions on the right, no custom flex
layout needed. */}
ComposeReplySaveOpen
Publish
{/* Main scroll region — a vertical stack of Surfaces, one per
card. Each card is a real Surface, never a
styled
to look like one. Add as many as your view needs. */}
Inbox
12 unread messages in your workspace.
Anna Lindberg
Quick question on the export pipeline
Staging run failed overnight — the schema validator is
rejecting the new locale rows. Have you seen this on prod
yet, or is it just the dev branch?
Marcus Webb
Design review notes — week 18
Loved the new inspector layout. Two small notes on toolbar
spacing and one question about how the accent ring renders
in light mode — happy to walk through tomorrow.
);
}
```
That's the entire shell. From here, fill the content surface with whatever your app needs — [`Input`](/react/components/input/), [`Select`](/react/components/select/), [`Dialog`](/react/components/dialog/), [`Popover`](/react/components/popover/), and the rest of the kit are designed to drop straight in.
## Reach for cladd primitives, not divs
The fastest way to make cladd code feel generic is to skip the primitives and style raw `
`s instead. The mapping:
| You want... | Use... |
| --------------------------------------------------- | -------------------------------------------------- |
| A panel, card, or any framed region | [`Surface`](/react/components/surface/) |
| An inset / recessed slot (code blocks, input wells) | [`SurfaceCut`](/react/components/surface-cut/) |
| A horizontal strip of action buttons | [`Toolbar`](/react/components/toolbar/) |
| A vertical row stack (sidebars, menus) | [`List`](/react/components/list/) |
| A status tag, count, or label | [`Chip`](/react/components/chip/) |
| A keyboard shortcut hint | [`Shortcut`](/react/components/shortcut/) |
| A grouped section eyebrow label | [`SectionTitle`](/react/components/section-title/) |
| A floating anchored panel | [`Popover`](/react/components/popover/) |
| A full-screen detail sheet | [`Popup`](/react/components/popup/) |
If you find yourself stacking `bg-cladd-surface` + `border` + `rounded-*` on a `
`, you almost certainly want a [`Surface`](/react/components/surface/) instead. Same goes for any "row of buttons" that ends up styled by hand — that's a [`Toolbar`](/react/components/toolbar/).
## Use the cladd tokens
For the parts that _aren't_ primitives — page backgrounds, soft body text, outline strokes — cladd exposes a tight set of Tailwind tokens:
- **Backgrounds** — `bg-cladd-bg`, `bg-cladd-surface`, `bg-cladd-surface-cut`, `bg-cladd-surface-minus`, `bg-cladd-surface-plus`
- **Text** — `text-cladd-fg`, `text-cladd-fg-soft`, `text-cladd-fg-softer`, `text-cladd-fg-softest`
- **Strokes** — `border-cladd-outline`
- **Accent** — `text-cladd-primary`
Do **not** invent suffixes (`bg-cladd-surface-2`, `text-cladd-fg-2`) — they don't exist. Stick to the exposed names.
## Icons
cladd is icon-agnostic — it ships no icon set. Use whatever your project already has: [Lucide](https://lucide.dev/), [Heroicons](https://heroicons.com/), [Tabler Icons](https://tabler.io/icons), or hand-rolled SVG components.
Two integration patterns:
- Components with an explicit `icon` prop ([`Chip`](/react/components/chip/), [`ListButton`](/react/components/list/)) take a component or a node:
```tsx
Active}>Inbox
```
- Everywhere else ([`Button`](/react/components/button/), [`ToolbarButton`](/react/components/toolbar/)), render the icon as a child:
```tsx
```
## Where to go next
Three foundation pages, in order:
1. [Surfaces](/react/foundations/surfaces/) — the depth model: levels, nesting, recessed vs. raised, contextual `useSurface`.
2. [Sizing](/react/foundations/sizing/) — the `2xs → 2xl` scale and how nested primitives like [`Chip`](/react/components/chip/) and [`Shortcut`](/react/components/shortcut/) auto-fit inside a [`Button`](/react/components/button/) or [`Input`](/react/components/input/) row.
3. [Colors](/react/foundations/colors/) — the eleven accent tokens and how to retune them with OKLCH variables.
Read those three and the remaining 90% of cladd is just looking up the right component.