---
title: "Toolkit UI Primitives"
description: "How to use @agent-native/toolkit UI primitives, the local app-adapter pattern, and shared shell hooks without locking apps out of customization."
---
# Toolkit UI Primitives
Toolkit UI primitives live under `@agent-native/toolkit/ui/*`. They are the
shared shadcn-style building blocks used by templates and reusable kits.
If your company already has a React component library, register it through the
semantic design-system bridge instead of replacing feature code. The bridge is
styling-runtime agnostic, supports partial adapters with per-control fallback,
and lets shared Toolkit and Core-owned feature views consume the same company
components. See [Custom Design Systems](/docs/custom-design-system) for the 17
semantic contracts, build-time theme tokens, conformance tests, and adapter
recipes.
UI primitives
Buttons
Input
Search...
Select
Editor
Badges
ActiveDraft
DialogDelete file?This cannot be undone.
Menu
Rename
Share
"
}
/>
Reusable package code can import them directly:
```tsx
import { Button } from "@agent-native/toolkit/ui/button";
import { Dialog, DialogContent } from "@agent-native/toolkit/ui/dialog";
```
Apps that render Toolkit UI must also import the Toolkit stylesheet from
`app/global.css` so Tailwind generates classes used only inside package
components, such as dropdown and popover z-index and animation utilities:
```css filename="app/global.css"
@import "tailwindcss";
@import "@agent-native/core/styles/agent-native.css";
@import "@agent-native/toolkit/styles.css";
```
## App adapters {#app-adapters}
Template app code should import a local adapter instead of a Toolkit
primitive directly:
```tsx
import { Button } from "@/components/ui/button";
```
Every template exposes these adapters under `@/components/ui/*`, and local
hook adapters under `@/hooks/*` (see [Shell hooks](#shell-hooks) below). Most
adapters are intentionally tiny — a one-line re-export:
```tsx filename="app/components/ui/button.tsx"
export * from "@agent-native/toolkit/ui/button";
```
One stable import path
Toolkit@agent-native/toolkit/ui/buttonDefault behavior and accessibility
App adapter@/components/ui/buttonRe-export, swap once to restyle
App screens
Settings
Share dialog
Command menu
"
}
/>
This pattern gives apps a stable customization point. Reusable Toolkit code can
ship once, while app owners can replace `Button`, `Input`, or `Dialog` locally
without rewriting every callsite: when an app wants its own button, it
replaces that one adapter file, and the rest of the app keeps importing
`@/components/ui/button`.
**Import rule:** inside app code, import from the local adapter
(`@/components/ui/button`); inside Toolkit or other reusable packages, import
directly from `@agent-native/toolkit/ui/*`. Reusable kit components that
render app chrome should prefer reading overridable primitives from
`ToolkitProvider` instead of importing an adapter directly — see
[Provider overrides](#provider-overrides) below.
### Provider overrides {#provider-overrides}
Reusable Toolkit UI should read overridable primitives from `ToolkitProvider`
instead of hard-coding a visual system. Templates wire their local `Button` into
that provider so future kits automatically pick up app customization.
```tsx filename="app/components/ui/toolkit-provider.tsx"
import { ToolkitProvider } from "@agent-native/toolkit/provider";
import { Button } from "@/components/ui/button";
export function AppToolkitProvider({
children,
}: {
children: React.ReactNode;
}) {
return {children};
}
```
If an app override wants to keep Toolkit's default button styling as its base,
render `ButtonBase` from `@agent-native/toolkit/ui/button`. Do not render
Toolkit's `Button` from inside the override; `ButtonBase` is the explicit escape
hatch, while Toolkit's recursion guard is only a fallback.
Existing template code that used direct Toolkit imports has been migrated to
local adapters, and new template code should follow the same pattern. Toolkit
still exports every primitive directly, so external, non-template packages can
keep importing `@agent-native/toolkit/ui/*` without adopting local adapters.
Core also keeps old imports working through its own re-export shims for code
written before Toolkit adapters existed.
For new customization, prefer `designSystem={designSystem}` over the legacy
`components={{ Button }}` override. The design-system adapter uses semantic
props such as intent, emphasis, pending state, controlled values, and controlled
open state rather than shadcn variant names. When both APIs provide the button,
`designSystem.components.ActionButton` wins. A missing or failed custom control
falls back to Toolkit’s default adapter without disabling the rest of the
registered system.
## Shell hooks {#shell-hooks}
Toolkit includes small shell helpers and hooks that are useful across apps:
Dashboards
Saved changes
"
}
/>
```tsx
import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
import { useIsMobile } from "@agent-native/toolkit/hooks/use-mobile";
import { useToast } from "@agent-native/toolkit/hooks/use-toast";
```
Apps wrap these through the same local-adapter pattern as UI primitives (see
[App adapters](#app-adapters) above):
```ts filename="app/hooks/use-mobile.ts"
export * from "@agent-native/toolkit/hooks/use-mobile";
```
Keep shell helpers in Toolkit when they are reusable and do not own app data.
Keep app-specific navigation, command entries, and domain state in the template.
Core remains responsible for framework-wide shell behavior such as app providers,
agent chat, app state, auth, and runtime sync.
## What's next
- [**Agent-Native Toolkit**](/docs/agent-native-toolkit) — the hub page linking
every kit and foundation piece.
- [**Sharing Kit**](/docs/toolkit-sharing) — another kit that splits Toolkit UI
from Core-owned runtime and access checks.
- [**Collaboration Kit**](/docs/toolkit-collaboration) — the same Toolkit/Core
split applied to realtime editing and presence.
- [**Component API**](/docs/components) — the generated reference for public
React exports, including the primitives covered here.