` props — they are forwarded to the underlying `Sidebar.Provider`.
### AppLayout.MenuToggle
An icon button that opens the mobile sidebar sheet (`Sidebar.Mobile`). **Mobile-only** — hidden on viewports above `768px`. Place it inside your `Navbar.Header` alongside the `Sidebar.Trigger`.
| Prop | Type | Default | Description |
| -------------- | ----------------------- | ---------- | ------------------------------------------------------------------- |
| `children` | `ReactNode` | `
# Area Chart
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/area-chart
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/area-chart.mdx
> An area chart for visualizing trends with gradient fills, stacked series, and sparkline variants.
## Usage
{/* DEMO area-chart-default */}
```tsx
"use client";
import { AreaChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
import { ChartTooltip } from "@thenamespace/uikit/chart-tooltip";
const revenueData = [
{ month: "Jan", revenue: 4200 },
{ month: "Feb", revenue: 5800 },
{ month: "Mar", revenue: 4900 },
{ month: "Apr", revenue: 7200 },
{ month: "May", revenue: 6100 },
{ month: "Jun", revenue: 8400 },
{ month: "Jul", revenue: 7800 },
{ month: "Aug", revenue: 9200 },
{ month: "Sep", revenue: 8600 },
{ month: "Oct", revenue: 10200 },
{ month: "Nov", revenue: 9800 },
{ month: "Dec", revenue: 11500 },
];
export const DemoDefaultExample = () => (
Monthly Revenue
`${(value / 1000).toFixed(0)}k`}
width={40}
/>
!active || !payload?.length ? null : (
{label}
{payload.map((entry) => (
{entry.name}
${Number(entry.value).toLocaleString()}
))}
)
}
/>
);
```
## Anatomy
Import the AreaChart component and access all parts using dot notation.
```tsx
import { AreaChart } from "@thenamespace/uikit";
;
```
## Custom Tooltip
{/* DEMO area-chart-custom-tooltip */}
```tsx
"use client";
import { AreaChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
import { ChartTooltip } from "@thenamespace/uikit/chart-tooltip";
const trafficData = [
{ month: "Jan", organic: 2000, paidAds: 1000 },
{ month: "Feb", organic: 5000, paidAds: 3000 },
{ month: "Mar", organic: 8000, paidAds: 5000 },
{ month: "Apr", organic: 7000, paidAds: 6000 },
{ month: "May", organic: 9500, paidAds: 4000 },
{ month: "Jun", organic: 8000, paidAds: 5500 },
{ month: "Jul", organic: 12000, paidAds: 7000 },
{ month: "Aug", organic: 11000, paidAds: 6500 },
{ month: "Sep", organic: 14000, paidAds: 8000 },
{ month: "Oct", organic: 13000, paidAds: 9000 },
{ month: "Nov", organic: 16000, paidAds: 10000 },
{ month: "Dec", organic: 15000, paidAds: 9500 },
];
function AxisSet() {
return (
<>
value >= 1000 ? `${(value / 1000).toFixed(0)}k` : `${value}`
}
width={30}
/>
);
}
function Legend({
items,
}: {
items: ReadonlyArray<{ color: string; label: string }>;
}) {
return (
Sessions
{[
["custom-organic", "var(--chart-3)"],
["custom-paid", "var(--chart-1)"],
].map(([id, color]) => (
))}
{
if (
!active ||
!payload?.length ||
!payload.every((entry) => typeof entry.value === "number")
)
return null;
const total = payload.reduce(
(sum, entry) => sum + Number(entry.value ?? 0),
0,
);
return (
{label}
{payload.map((entry, index) => (
{entry.name}
{Number(entry.value).toLocaleString()}
))}
);
}}
/>
);
```
## KPI With Area Chart
{/* DEMO area-chart-kpiwith-area-chart */}
```tsx
"use client";
import { AreaChart } from "@thenamespace/uikit";
import { KPI } from "@thenamespace/uikit/kpi";
import { TrendChip } from "@thenamespace/uikit/trend-chip";
const sparkUp = [30, 35, 28, 42, 38, 45, 50, 48, 55, 60, 58, 65].map((value) => ({ value }));
const sparkDown = [65, 60, 62, 55, 58, 52, 50, 48, 45, 42, 44, 40].map((value) => ({ value }));
const kpis = [
{
color: "var(--chart-3)",
data: sparkUp,
direction: "up",
id: "kpi-revenue",
label: "Total Revenue",
suffix: "last 30d",
trend: "3.3%",
value: "US$228,451",
},
{
color: "var(--color-danger)",
data: sparkDown,
direction: "down",
id: "kpi-bounce",
label: "Bounce Rate",
suffix: "vs last 7d",
trend: "5.9%",
value: "42.3%",
},
{
color: "var(--color-success)",
data: sparkUp,
direction: "up",
id: "kpi-users",
label: "Active Users",
suffix: "this month",
trend: "10.9%",
value: "98k",
},
] as const;
export const DemoKPIWithAreaChartExample = () => (
value >= 1000 ? `${(value / 1000).toFixed(0)}k` : `${value}`
}
width={30}
/>
);
}
function Legend({
items,
}: {
items: ReadonlyArray<{ color: string; label: string }>;
}) {
return (
Traffic Sources
{[
["organic-fill", "var(--chart-3)"],
["paidads-fill", "var(--chart-1)"],
].map(([id, color]) => (
))}
);
```
## Sparkline
{/* DEMO area-chart-sparkline */}
```tsx
"use client";
import { AreaChart } from "@thenamespace/uikit";
const sparkUp = [30, 35, 28, 42, 38, 45, 50, 48, 55, 60, 58, 65].map(
(value) => ({ value }),
);
const sparkDown = [65, 60, 62, 55, 58, 52, 50, 48, 45, 42, 44, 40].map(
(value) => ({ value }),
);
function SparkArea({
color,
data,
id,
label,
}: {
color: string;
data: { value: number }[];
id: string;
label: string;
}) {
return (
value >= 1000 ? `${(value / 1000).toFixed(0)}k` : `${value}`
}
width={30}
/>
);
}
function Legend({
items,
}: {
items: ReadonlyArray<{ color: string; label: string }>;
}) {
return (
Traffic Breakdown
{series.map(({ color, key }) => (
))}
);
};
```
## CSS Classes
### Element Classes
- `.area-chart` — Root container wrapping `ResponsiveContainer` and the Recharts chart.
### Recharts Theming
The following CSS rules target Recharts internal class names to apply Namespace UIKit design tokens automatically:
- `.area-chart .recharts-cartesian-axis-tick-value` — Axis tick labels. 10px muted text.
- `.area-chart .recharts-cartesian-axis-line` — Axis lines. Hidden by default.
- `.area-chart .recharts-cartesian-axis-tick-line` — Tick lines. Hidden by default.
- `.area-chart .recharts-cartesian-grid line` — Cartesian grid lines. Muted stroke at 0.15 opacity.
- `.area-chart .recharts-tooltip-cursor` — Tooltip cursor. Dashed vertical line on hover.
- `.area-chart .recharts-active-dot circle` — Active dot. Outlined with surface color for contrast.
## API Reference
### AreaChart
The root wrapper. Renders a `ResponsiveContainer` + Recharts `AreaChart` with Namespace UIKit CSS theming applied automatically.
| Prop | Type | Default | Description |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------- |
| `data` | `Record[]` | — | Chart data — array of objects with numeric/string fields for each series. |
| `height` | `number` | `300` | Chart height in pixels. |
| `width` | ``number \| `${number}%` `` | `"100%"` | Chart width in pixels or percentage string. |
| `margin` | `{ top?: number; right?: number; bottom?: number; left?: number }` | `{ top: 8, right: 8, bottom: 0, left: 0 }` | Recharts margin around the chart area. |
| `children` | `ReactNode` | — | Recharts child components (`AreaChart.Area`, `AreaChart.XAxis`, etc.). |
Also supports all native `div` HTML attributes.
### AreaChart.Area
Re-exported Recharts `Area` component. Follows the [Recharts Area API](https://recharts.github.io/en-US/api/Area/).
### AreaChart.XAxis
Re-exported Recharts `XAxis` component. Follows the [Recharts XAxis API](https://recharts.github.io/en-US/api/XAxis/).
### AreaChart.YAxis
Re-exported Recharts `YAxis` component. Follows the [Recharts YAxis API](https://recharts.github.io/en-US/api/YAxis/).
### AreaChart.Grid
Re-exported Recharts `CartesianGrid` component. Follows the [Recharts CartesianGrid API](https://recharts.github.io/en-US/api/CartesianGrid/).
### AreaChart.Tooltip
Re-exported Recharts `Tooltip` component. Follows the [Recharts Tooltip API](https://recharts.github.io/en-US/api/Tooltip/). Use with `AreaChart.TooltipContent` for styled tooltips.
### AreaChart.TooltipContent
Pre-built tooltip renderer for Recharts. Pass as the `content` prop of `AreaChart.Tooltip`. See [ChartTooltip](/react/components/chart-tooltip) for full props.
# Autocomplete
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/autocomplete
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/autocomplete.mdx
> An autocomplete combines a select with filtering, allowing users to search and select from a list of options
## Import
```tsx
import { Autocomplete, useFilter } from "@thenamespace/uikit";
```
### Usage
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
EmptyState,
Label,
ListBox,
SearchField,
Tag,
TagGroup,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
export default function Default() {
const {contains} = useFilter({sensitivity: "base"});
const [selectedKeys, setSelectedKeys] = useState([]);
const items = [
{id: "florida", name: "Florida"},
{id: "delaware", name: "Delaware"},
{id: "california", name: "California"},
{id: "texas", name: "Texas"},
{id: "new-york", name: "New York"},
{id: "washington", name: "Washington"},
];
const onRemoveTags = (keys: Set) => {
setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
};
return (
setSelectedKeys(keys as Key[])}
>
{({defaultChildren, isPlaceholder, state}: any) => {
if (isPlaceholder || state.selectedItems.length === 0) {
return defaultChildren;
}
const selectedItemsKeys = state.selectedItems.map((item: any) => item.key);
return (
{selectedItemsKeys.map((selectedItemKey: Key) => {
const item = items.find((s) => s.id === selectedItemKey);
if (!item) return null;
return (
{item.name}
);
})}
);
}}
No results found }>
{items.map((item) => (
{item.name}
))}
);
}
```
### Anatomy
Import the Autocomplete component and access all parts using dot notation.
```tsx
import {
Autocomplete,
Label,
Description,
SearchField,
ListBox,
} from "@thenamespace/uikit";
export default () => (
);
```
### With Description
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
Description,
EmptyState,
Label,
ListBox,
SearchField,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
export function WithDescription() {
const [selectedKey, setSelectedKey] = useState(null);
const {contains} = useFilter({sensitivity: "base"});
const items = [
{id: "florida", name: "Florida"},
{id: "delaware", name: "Delaware"},
{id: "california", name: "California"},
{id: "texas", name: "Texas"},
{id: "new-york", name: "New York"},
{id: "washington", name: "Washington"},
];
return (
No results found }>
{items.map((item) => (
{item.name}
))}
Select your state of residence
);
}
```
### Multiple Select
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
EmptyState,
Label,
ListBox,
SearchField,
Tag,
TagGroup,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
export function MultipleSelect() {
const [selectedKeys, setSelectedKeys] = useState([]);
const {contains} = useFilter({sensitivity: "base"});
const items = [
{id: "california", name: "California"},
{id: "texas", name: "Texas"},
{id: "florida", name: "Florida"},
{id: "new-york", name: "New York"},
{id: "illinois", name: "Illinois"},
{id: "pennsylvania", name: "Pennsylvania"},
];
const onRemoveTags = (keys: Set) => {
setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
};
return (
setSelectedKeys(keys as Key[])}
>
{({defaultChildren, isPlaceholder, state}) => {
if (isPlaceholder || state.selectedItems.length === 0) {
return defaultChildren;
}
const selectedItemsKeys = state.selectedItems.map((item) => item.key);
return (
{selectedItemsKeys.map((selectedItemKey) => {
const item = items.find((s) => s.id === selectedItemKey);
if (!item) return null;
return (
{item.name}
);
})}
);
}}
No results found }>
{items.map((item) => (
{item.name}
))}
);
}
```
### With Sections
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
EmptyState,
Header,
Label,
ListBox,
SearchField,
Separator,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
export function WithSections() {
const [selectedKey, setSelectedKey] = useState(null);
const {contains} = useFilter({sensitivity: "base"});
return (
No results found }>
North America
United States
Canada
Mexico
Europe
United Kingdom
France
Germany
Spain
Italy
Asia
Japan
China
India
South Korea
);
}
```
### With Disabled Options
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@thenamespace/uikit";
import {useState} from "react";
export function WithDisabledOptions() {
const [selectedKey, setSelectedKey] = useState(null);
const {contains} = useFilter({sensitivity: "base"});
return (
No results found }>
Dog
Cat
Bird
Kangaroo
Elephant
Tiger
);
}
```
### Allows Empty Collection
The `allowsEmptyCollection` prop enables the autocomplete to function even when there are no items in the collection. This is useful for scenarios where the list might be empty initially or when all items are filtered out.
```tsx
"use client";
import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@thenamespace/uikit";
export function AllowsEmptyCollection() {
const {contains} = useFilter({sensitivity: "base"});
return (
No results found } />
);
}
```
### Custom Indicator
```tsx
"use client";
import { useState } from "react";
import type { Key } from "@thenamespace/uikit";
import {
Autocomplete,
EmptyState,
Label,
ListBox,
SearchField,
useFilter,
} from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
export function CustomIndicator() {
const [selectedKey, setSelectedKey] = useState(null);
const { contains } = useFilter({ sensitivity: "base" });
const items = [
{ id: "florida", name: "Florida" },
{ id: "delaware", name: "Delaware" },
{ id: "california", name: "California" },
{ id: "texas", name: "Texas" },
{ id: "new-york", name: "New York" },
{ id: "washington", name: "Washington" },
];
return (
No results found }>
{items.map((item) => (
{item.name}
))}
);
}
```
### Required
```tsx
"use client";
import {
Autocomplete,
Button,
EmptyState,
FieldError,
Form,
Label,
ListBox,
SearchField,
useFilter,
} from "@thenamespace/uikit";
export function Required() {
const onSubmit = (e: React.FormEvent) => {
e.preventDefault();
const formData = new FormData(e.currentTarget);
const data: Record = {};
// Convert FormData to plain object
formData.forEach((value, key) => {
data[key] = value.toString();
});
alert("Form submitted successfully!");
};
const {contains} = useFilter({sensitivity: "base"});
const states = [
{id: "florida", name: "Florida"},
{id: "delaware", name: "Delaware"},
{id: "california", name: "California"},
{id: "texas", name: "Texas"},
{id: "new-york", name: "New York"},
{id: "washington", name: "Washington"},
];
const countries = [
{id: "usa", name: "United States"},
{id: "canada", name: "Canada"},
{id: "mexico", name: "Mexico"},
{id: "uk", name: "United Kingdom"},
{id: "france", name: "France"},
{id: "germany", name: "Germany"},
];
return (
);
}
```
### Full Width
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
EmptyState,
Label,
ListBox,
SearchField,
Surface,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
export function FullWidth() {
const [selectedKey, setSelectedKey] = useState(null);
const {contains} = useFilter({sensitivity: "base"});
const items = [
{id: "florida", name: "Florida"},
{id: "delaware", name: "Delaware"},
{id: "california", name: "California"},
{id: "texas", name: "Texas"},
{id: "new-york", name: "New York"},
{id: "washington", name: "Washington"},
];
return (
No results found }>
{items.map((item) => (
{item.name}
))}
);
}
```
### Variants
The Autocomplete component supports two visual variants:
- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
EmptyState,
Label,
ListBox,
SearchField,
Tag,
TagGroup,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
export function Variants() {
const [selectedKey1, setSelectedKey1] = useState(null);
const [selectedKey2, setSelectedKey2] = useState(null);
const [selectedKeys1, setSelectedKeys1] = useState([]);
const [selectedKeys2, setSelectedKeys2] = useState([]);
const {contains} = useFilter({sensitivity: "base"});
const items = [
{id: "option1", name: "Option 1"},
{id: "option2", name: "Option 2"},
{id: "option3", name: "Option 3"},
{id: "option4", name: "Option 4"},
];
const onRemoveTags1 = (keys: Set) => {
setSelectedKeys1((prev) => prev.filter((key) => !keys.has(key)));
};
const onRemoveTags2 = (keys: Set) => {
setSelectedKeys2((prev) => prev.filter((key) => !keys.has(key)));
};
return (
No results found }>
{items.map((item) => (
{item.name}
))}
No results found }>
{items.map((item) => (
{item.name}
))}
setSelectedKeys1(keys as Key[])}
>
{({defaultChildren, isPlaceholder, state}) => {
if (isPlaceholder || state.selectedItems.length === 0) {
return defaultChildren;
}
const selectedItemsKeys = state.selectedItems.map((item) => item.key);
return (
{selectedItemsKeys.map((selectedItemKey) => {
const item = items.find((s) => s.id === selectedItemKey);
if (!item) return null;
return (
{item.name}
);
})}
);
}}
No results found }>
{items.map((item) => (
{item.name}
))}
setSelectedKeys2(keys as Key[])}
>
{({defaultChildren, isPlaceholder, state}) => {
if (isPlaceholder || state.selectedItems.length === 0) {
return defaultChildren;
}
const selectedItemsKeys = state.selectedItems.map((item) => item.key);
return (
{selectedItemsKeys.map((selectedItemKey) => {
const item = items.find((s) => s.id === selectedItemKey);
if (!item) return null;
return (
{item.name}
);
})}
);
}}
No results found }>
{items.map((item) => (
{item.name}
))}
);
}
```
### In Surface
When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
EmptyState,
Label,
ListBox,
SearchField,
Surface,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
export function FullWidth() {
const [selectedKey, setSelectedKey] = useState(null);
const {contains} = useFilter({sensitivity: "base"});
const items = [
{id: "florida", name: "Florida"},
{id: "delaware", name: "Delaware"},
{id: "california", name: "California"},
{id: "texas", name: "Texas"},
{id: "new-york", name: "New York"},
{id: "washington", name: "Washington"},
];
return (
No results found }>
{items.map((item) => (
{item.name}
))}
);
}
```
### Custom Value
You can customize the displayed value using render props:
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
Avatar,
AvatarFallback,
AvatarImage,
Description,
EmptyState,
Label,
ListBox,
SearchField,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
export function UserSelection() {
const users = [
{
avatarUrl: "/assets/avatars/blue.jpg",
email: "bob@namespace.ninja",
fallback: "B",
id: "1",
name: "Bob",
},
{
avatarUrl: "/assets/avatars/green.jpg",
email: "fred@namespace.ninja",
fallback: "F",
id: "2",
name: "Fred",
},
{
avatarUrl: "/assets/avatars/purple.jpg",
email: "martha@namespace.ninja",
fallback: "M",
id: "3",
name: "Martha",
},
{
avatarUrl: "/assets/avatars/red.jpg",
email: "john@namespace.ninja",
fallback: "J",
id: "4",
name: "John",
},
{
avatarUrl: "/assets/avatars/orange.jpg",
email: "jane@namespace.ninja",
fallback: "J",
id: "5",
name: "Jane",
},
];
const [selectedKey, setSelectedKey] = useState(null);
const {contains} = useFilter({sensitivity: "base"});
return (
{({defaultChildren, isPlaceholder, state}) => {
if (isPlaceholder || state.selectedItems.length === 0) {
return defaultChildren;
}
const selectedItems = state.selectedItems;
if (selectedItems.length > 1) {
return `${selectedItems.length} users selected`;
}
const selectedItem = users.find((user) => user.id === selectedItems[0]?.key);
if (!selectedItem) {
return defaultChildren;
}
return (
{selectedItem.fallback}
{selectedItem.name}
);
}}
No results found }>
{users.map((user) => (
{user.fallback}
{user.email}
))}
);
}
```
### Controlled
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@thenamespace/uikit";
import {useState} from "react";
export function Controlled() {
const states = [
{id: "california", name: "California"},
{id: "texas", name: "Texas"},
{id: "florida", name: "Florida"},
{id: "new-york", name: "New York"},
{id: "illinois", name: "Illinois"},
{id: "pennsylvania", name: "Pennsylvania"},
];
const [state, setState] = useState("california");
const {contains} = useFilter({sensitivity: "base"});
const selectedState = states.find((s) => s.id === state);
return (
No results found }>
{states.map((state) => (
{state.name}
))}
);
}
```
### Controlled Multiple
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
EmptyState,
Label,
ListBox,
SearchField,
Tag,
TagGroup,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
export function MultipleSelect() {
const [selectedKeys, setSelectedKeys] = useState([]);
const {contains} = useFilter({sensitivity: "base"});
const items = [
{id: "california", name: "California"},
{id: "texas", name: "Texas"},
{id: "florida", name: "Florida"},
{id: "new-york", name: "New York"},
{id: "illinois", name: "Illinois"},
{id: "pennsylvania", name: "Pennsylvania"},
];
const onRemoveTags = (keys: Set) => {
setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
};
return (
setSelectedKeys(keys as Key[])}
>
{({defaultChildren, isPlaceholder, state}) => {
if (isPlaceholder || state.selectedItems.length === 0) {
return defaultChildren;
}
const selectedItemsKeys = state.selectedItems.map((item) => item.key);
return (
{selectedItemsKeys.map((selectedItemKey) => {
const item = items.find((s) => s.id === selectedItemKey);
if (!item) return null;
return (
{item.name}
);
})}
);
}}
No results found }>
{items.map((item) => (
{item.name}
))}
);
}
```
### Controlled Open State
```tsx
"use client";
import {
Autocomplete,
Button,
EmptyState,
Label,
ListBox,
SearchField,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
export function ControlledOpenState() {
const [isOpen, setIsOpen] = useState(false);
const {contains} = useFilter({sensitivity: "base"});
const items = [
{id: "florida", name: "Florida"},
{id: "delaware", name: "Delaware"},
{id: "california", name: "California"},
{id: "texas", name: "Texas"},
{id: "new-york", name: "New York"},
{id: "washington", name: "Washington"},
];
return (
No results found }>
{items.map((item) => (
{item.name}
))}
);
}
```
### Asynchronous Filtering
```tsx
"use client";
import {Autocomplete, EmptyState, Label, ListBox, SearchField, Spinner} from "@thenamespace/uikit";
import {useAsyncList} from "@react-stately/data";
import {cn} from "tailwind-variants";
interface Character {
name: string;
}
export function AsynchronousFiltering() {
const list = useAsyncList({
async load({filterText, signal}) {
const res = await fetch(`https://swapi.py4e.com/api/people/?search=${filterText}`, {
signal,
});
const json = await res.json();
return {
items: json.results,
};
},
});
return (
No results found }
>
{(item: Character) => (
{item.name}
)}
);
}
```
### Virtualization
Autocomplete supports virtualization through [Virtualizer](https://react-aria.adobe.com/Virtualizer), enabling efficient rendering of large datasets by displaying only the rows visible within the viewport.
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
Description,
EmptyState,
Label,
ListBox,
ListLayout,
SearchField,
Virtualizer,
useFilter,
} from "@thenamespace/uikit";
import {useMemo, useState} from "react";
interface User {
email: string;
id: number;
name: string;
}
function generateUsers(n: number): User[] {
const firstNames = [
"Emma",
"Liam",
"Olivia",
"Noah",
"Ava",
"James",
"Sophia",
"Oliver",
"Isabella",
"Lucas",
"Mia",
"Ethan",
"Charlotte",
"Mason",
"Amelia",
"Logan",
"Harper",
"Alexander",
"Ella",
"Benjamin",
];
const lastNames = [
"Smith",
"Johnson",
"Williams",
"Brown",
"Jones",
"Garcia",
"Miller",
"Davis",
"Rodriguez",
"Martinez",
"Anderson",
"Taylor",
"Thomas",
"Jackson",
"White",
"Harris",
"Clark",
"Lewis",
"Robinson",
"Walker",
];
const users: User[] = [];
for (let i = 0; i < n; i++) {
const firstName = firstNames[i % firstNames.length]!;
const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length]!;
const name = `${firstName} ${lastName}`;
users.push({
email: `${firstName.toLowerCase()}.${lastName.toLowerCase()}@acme.com`,
id: i + 1,
name,
});
}
return users;
}
export function Virtualization() {
const [selectedKey, setSelectedKey] = useState(null);
const [searchQuery, setSearchQuery] = useState("");
const {contains} = useFilter({sensitivity: "base"});
const allUsers = useMemo(() => generateUsers(1000), []);
const filteredUsers = useMemo(() => {
if (!searchQuery) return allUsers;
return allUsers.filter(
(user) => contains(user.name, searchQuery) || contains(user.email, searchQuery),
);
}, [allUsers, contains, searchQuery]);
return (
No results found }
>
{(user) => (
{user.email}
)}
);
}
```
### Disabled
```tsx
"use client";
import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@thenamespace/uikit";
export function Disabled() {
const {contains} = useFilter({sensitivity: "base"});
const items = [
{id: "florida", name: "Florida"},
{id: "delaware", name: "Delaware"},
{id: "california", name: "California"},
{id: "texas", name: "Texas"},
{id: "new-york", name: "New York"},
{id: "washington", name: "Washington"},
];
const countries = [
{id: "argentina", name: "Argentina"},
{id: "venezuela", name: "Venezuela"},
{id: "japan", name: "Japan"},
{id: "france", name: "France"},
{id: "italy", name: "Italy"},
{id: "spain", name: "Spain"},
];
return (
No results found }>
{items.map((item) => (
{item.name}
))}
No results found }>
{countries.map((country) => (
{country.name}
))}
);
}
```
### Advanced Examples
#### User Selection
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
Avatar,
AvatarFallback,
AvatarImage,
Description,
EmptyState,
Label,
ListBox,
SearchField,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
export function UserSelection() {
const users = [
{
avatarUrl: "/assets/avatars/blue.jpg",
email: "bob@namespace.ninja",
fallback: "B",
id: "1",
name: "Bob",
},
{
avatarUrl: "/assets/avatars/green.jpg",
email: "fred@namespace.ninja",
fallback: "F",
id: "2",
name: "Fred",
},
{
avatarUrl: "/assets/avatars/purple.jpg",
email: "martha@namespace.ninja",
fallback: "M",
id: "3",
name: "Martha",
},
{
avatarUrl: "/assets/avatars/red.jpg",
email: "john@namespace.ninja",
fallback: "J",
id: "4",
name: "John",
},
{
avatarUrl: "/assets/avatars/orange.jpg",
email: "jane@namespace.ninja",
fallback: "J",
id: "5",
name: "Jane",
},
];
const [selectedKey, setSelectedKey] = useState(null);
const {contains} = useFilter({sensitivity: "base"});
return (
{({defaultChildren, isPlaceholder, state}) => {
if (isPlaceholder || state.selectedItems.length === 0) {
return defaultChildren;
}
const selectedItems = state.selectedItems;
if (selectedItems.length > 1) {
return `${selectedItems.length} users selected`;
}
const selectedItem = users.find((user) => user.id === selectedItems[0]?.key);
if (!selectedItem) {
return defaultChildren;
}
return (
{selectedItem.fallback}
{selectedItem.name}
);
}}
No results found }>
{users.map((user) => (
{user.fallback}
{user.email}
))}
);
}
```
#### User Selection Multiple
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
Avatar,
AvatarFallback,
AvatarImage,
Description,
EmptyState,
Label,
ListBox,
SearchField,
Tag,
TagGroup,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
export function UserSelectionMultiple() {
const users = [
{
avatarUrl: "/assets/avatars/blue.jpg",
email: "bob@namespace.ninja",
fallback: "B",
id: "1",
name: "Bob",
},
{
avatarUrl: "/assets/avatars/green.jpg",
email: "fred@namespace.ninja",
fallback: "F",
id: "2",
name: "Fred",
},
{
avatarUrl: "/assets/avatars/purple.jpg",
email: "martha@namespace.ninja",
fallback: "M",
id: "3",
name: "Martha",
},
{
avatarUrl: "/assets/avatars/red.jpg",
email: "john@namespace.ninja",
fallback: "J",
id: "4",
name: "John",
},
{
avatarUrl: "/assets/avatars/orange.jpg",
email: "jane@namespace.ninja",
fallback: "J",
id: "5",
name: "Jane",
},
];
const [selectedKeys, setSelectedKeys] = useState([]);
const {contains} = useFilter({sensitivity: "base"});
const onRemoveTags = (keys: Set) => {
setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
};
return (
setSelectedKeys(keys as Key[])}
>
{({defaultChildren, isPlaceholder, state}) => {
if (isPlaceholder || state.selectedItems.length === 0) {
return defaultChildren;
}
const selectedItemsKeys = state.selectedItems.map((item) => item.key);
return (
{selectedItemsKeys.map((selectedItemKey) => {
const selectedItem = users.find((user) => user.id === selectedItemKey);
if (!selectedItem) {
return null;
}
return (
{selectedItem.fallback}
{selectedItem.name}
);
})}
);
}}
No results found }>
{users.map((user) => (
{user.fallback}
{user.email}
))}
);
}
```
#### Location Search
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
Description,
EmptyState,
Label,
ListBox,
SearchField,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
interface City {
name: string;
country: string;
}
export function LocationSearch() {
const allCities: City[] = [
{country: "USA", name: "New York"},
{country: "USA", name: "Los Angeles"},
{country: "USA", name: "Chicago"},
{country: "UK", name: "London"},
{country: "France", name: "Paris"},
{country: "Japan", name: "Tokyo"},
{country: "Australia", name: "Sydney"},
{country: "Canada", name: "Toronto"},
{country: "Germany", name: "Berlin"},
{country: "Spain", name: "Madrid"},
];
const [selectedKey, setSelectedKey] = useState(null);
const [isLoading, setIsLoading] = useState(false);
const {contains} = useFilter({sensitivity: "base"});
// Simulate async filtering
const customFilter = (text: string, inputValue: string) => {
if (!inputValue) return true;
setIsLoading(true);
setTimeout(() => setIsLoading(false), 300);
return contains(text, inputValue);
};
return (
(
{isLoading ? "Searching..." : "No cities found"}
)}
>
{allCities.map((city) => (
{city.country}
))}
);
}
```
#### Tag Group Selection
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
EmptyState,
Label,
ListBox,
SearchField,
Tag,
TagGroup,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
export function TagGroupSelection() {
const tags = [
{id: "react", name: "React"},
{id: "typescript", name: "TypeScript"},
{id: "javascript", name: "JavaScript"},
{id: "nodejs", name: "Node.js"},
{id: "python", name: "Python"},
{id: "vue", name: "Vue"},
{id: "angular", name: "Angular"},
{id: "nextjs", name: "Next.js"},
];
const [selectedKeys, setSelectedKeys] = useState([]);
const {contains} = useFilter({sensitivity: "base"});
const onRemoveTags = (keys: Set) => {
setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
};
return (
setSelectedKeys(keys as Key[])}
>
{({defaultChildren, isPlaceholder, state}) => {
if (isPlaceholder || state.selectedItems.length === 0) {
return defaultChildren;
}
const selectedItemsKeys = state.selectedItems.map((item) => item.key);
return (
{selectedItemsKeys.map((selectedItemKey) => {
const tag = tags.find((t) => t.id === selectedItemKey);
if (!tag) return null;
return (
{tag.name}
);
})}
);
}}
No tags found }>
{tags.map((tag) => (
{tag.name}
))}
);
}
```
#### Email Recipients
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {
Autocomplete,
Description,
EmptyState,
Label,
ListBox,
SearchField,
Tag,
TagGroup,
useFilter,
} from "@thenamespace/uikit";
import {useState} from "react";
export function EmailRecipients() {
const emails = [
{email: "alice@example.com", id: "alice@example.com", name: "Alice Johnson"},
{email: "bob@example.com", id: "bob@example.com", name: "Bob Smith"},
{email: "charlie@example.com", id: "charlie@example.com", name: "Charlie Brown"},
{email: "diana@example.com", id: "diana@example.com", name: "Diana Prince"},
{email: "eve@example.com", id: "eve@example.com", name: "Eve Wilson"},
];
const [selectedKeys, setSelectedKeys] = useState([]);
const {contains} = useFilter({sensitivity: "base"});
const onRemoveTags = (keys: Set) => {
setSelectedKeys((prev) => prev.filter((key) => !keys.has(key)));
};
return (
setSelectedKeys(keys as Key[])}
>
{({defaultChildren, isPlaceholder, state}) => {
if (isPlaceholder || state.selectedItems.length === 0) {
return defaultChildren;
}
const selectedItemsKeys = state.selectedItems.map((item) => item.key);
return (
{selectedItemsKeys.map((selectedItemKey) => {
const email = emails.find((e) => e.id === selectedItemKey);
if (!email) return null;
return (
{email.email}
);
})}
);
}}
No recipients found }>
{emails.map((email) => (
{email.email}
))}
);
}
```
## Styling
### Passing Tailwind CSS classes
```tsx
import { Autocomplete, SearchField, ListBox } from "@thenamespace/uikit";
function CustomAutocomplete() {
return (
Item 1
);
}
```
### Customizing the component classes
To customize the Autocomplete component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.autocomplete {
@apply flex flex-col gap-1;
}
.autocomplete__trigger {
@apply rounded-lg border border-border bg-surface p-2;
}
.autocomplete__value {
@apply text-current;
}
.autocomplete__clear-button {
@apply text-muted hover:text-foreground;
}
.autocomplete__indicator {
@apply text-muted;
}
.autocomplete__popover {
@apply rounded-lg border border-border bg-surface p-2;
}
.autocomplete__popover-dialog {
@apply outline-none;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The Autocomplete component uses these CSS classes:
#### Base Classes
- `.autocomplete` - Base autocomplete container
- `.autocomplete__trigger` - The button that triggers the autocomplete
- `.autocomplete__value` - The displayed value or placeholder
- `.autocomplete__clear-button` - The clear button that removes the selected value
- `.autocomplete__indicator` - The dropdown indicator icon
- `.autocomplete__popover` - The popover container
- `.autocomplete__popover-dialog` - Internal dialog wrapper inside the popover for focus management (matches [Popover](/docs/components/popover) behavior)
- `.autocomplete__filter` - The filter wrapper
#### Variant Classes
- `.autocomplete--primary` - Primary variant with shadow (default)
- `.autocomplete--secondary` - Secondary variant without shadow, suitable for use in surfaces
#### State Classes
- `.autocomplete[data-invalid="true"]` - Invalid state
- `.autocomplete__trigger[data-focus-visible="true"]` - Focused trigger state
- `.autocomplete__trigger[data-disabled="true"]` - Disabled trigger state
- `.autocomplete__value[data-placeholder="true"]` - Placeholder state
- `.autocomplete__clear-button[data-empty="true"]` - Clear button hidden when no selection
- `.autocomplete__indicator[data-open="true"]` - Open indicator state
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
- **Hover**: `:hover` or `[data-hovered="true"]` on trigger
- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger
- **Disabled**: `:disabled` or `[data-disabled="true"]` on autocomplete
- **Open**: `[data-open="true"]` on indicator
## API Reference
### Autocomplete Props
| Prop | Type | Default | Description |
| ----------------------- | --------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `placeholder` | `string` | `'Select an item'` | Temporary text that occupies the autocomplete when it is empty |
| `selectionMode` | `"single" \| "multiple"` | `"single"` | Whether single or multiple selection is enabled |
| `allowsEmptyCollection` | `boolean` | `false` | Whether the autocomplete allows an empty collection. When true, the autocomplete can function even with no items. |
| `isOpen` | `boolean` | - | Sets the open state of the popover (controlled) |
| `defaultOpen` | `boolean` | - | Sets the default open state of the popover (uncontrolled) |
| `onOpenChange` | `(isOpen: boolean) => void` | - | Handler called when the open state changes |
| `disabledKeys` | `Iterable` | - | Keys of disabled items |
| `isDisabled` | `boolean` | - | Whether the autocomplete is disabled |
| `value` | `Key \| Key[] \| null` | - | Current value (controlled) |
| `defaultValue` | `Key \| Key[] \| null` | - | Default value (uncontrolled) |
| `onChange` | `(value: Key \| Key[] \| null) => void` | - | Handler called when the value changes |
| `isRequired` | `boolean` | - | Whether user input is required |
| `isInvalid` | `boolean` | - | Whether the autocomplete value is invalid |
| `name` | `string` | - | The name of the input, used when submitting an HTML form |
| `fullWidth` | `boolean` | `false` | Whether the autocomplete should take full width of its container |
| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Autocomplete content or render function |
### Autocomplete.Trigger Props
| Prop | Type | Default | Description |
| ----------- | ----------------------------- | ------- | ---------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Trigger content or render function |
### Autocomplete.Value Props
| Prop | Type | Default | Description |
| ----------- | ----------------------------- | ------- | -------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Value content or render function |
### Autocomplete.Indicator Props
| Prop | Type | Default | Description |
| ----------- | ----------- | ------- | ------------------------ |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode` | - | Custom indicator content |
### Autocomplete.ClearButton Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------ | ------- | ------------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `onClick` | `(e: MouseEvent) => void` | - | Handler called when button is clicked |
| `ref` | `RefObject` | - | Ref to the clear button element |
### Autocomplete.Popover Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | Placement of the popover relative to the trigger |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode` | - | Content children. Wrapped internally in a dialog element for focus management, styled with `.autocomplete__popover-dialog`. |
### Autocomplete.Filter Props
| Prop | Type | Default | Description |
| --------------- | ------------------------------------------ | ------- | ---------------------------------------- |
| `filter` | `(text: string, input: string) => boolean` | - | Custom filter function |
| `inputValue` | `string` | - | Controlled input value |
| `onInputChange` | `(value: string) => void` | - | Handler called when input value changes |
| `children` | `ReactNode` | - | Filter content (SearchField and ListBox) |
### useFilter Hook
The `useFilter` hook from React Aria provides filtering functions for autocomplete functionality.
```tsx
import { useFilter } from "@thenamespace/uikit";
const { contains } = useFilter({ sensitivity: "base" });
...
...
;
```
**Options:**
| Option | Type | Default | Description |
| ------------- | ------------------------------------------- | -------- | ------------------------------- |
| `sensitivity` | `"base" \| "accent" \| "case" \| "variant"` | `"base"` | Locale sensitivity for matching |
**Returns:**
| Function | Type | Description |
| ------------ | ------------------------------------------------ | ------------------------------------------------------ |
| `contains` | `(string: string, substring: string) => boolean` | Returns whether a string contains a given substring |
| `startsWith` | `(string: string, substring: string) => boolean` | Returns whether a string starts with a given substring |
| `endsWith` | `(string: string, substring: string) => boolean` | Returns whether a string ends with a given substring |
### RenderProps
When using render functions with Autocomplete.Value, these values are provided:
| Prop | Type | Description |
| ----------------- | ------------- | ---------------------------------- |
| `defaultChildren` | `ReactNode` | The default rendered value |
| `isPlaceholder` | `boolean` | Whether the value is a placeholder |
| `state` | `SelectState` | The state of the autocomplete |
| `selectedItems` | `Node[]` | The currently selected items |
## Accessibility
The Autocomplete component implements the ARIA select pattern with filtering and provides:
- Full keyboard navigation support
- Screen reader announcements for selection changes
- Focus management aligned with [Popover](/docs/components/popover): `Autocomplete.Popover` wraps its content in an internal dialog so touch interactions do not show a stray focus ring on the popover overlay
- Support for disabled states
- Search functionality with filtering
- HTML form integration
Use `autoFocus={false}` on `SearchField` when you want to avoid opening the mobile keyboard as soon as the popover appears. Filtering still works once the user focuses the search input.
For more information, see the [React Aria Select documentation](https://react-spectrum.adobe.com/react-aria/Select.html).
# Avatar
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/avatar
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/avatar.mdx
> Display user profile images with customizable fallback content
## Import
```tsx
import { Avatar } from "@thenamespace/uikit";
```
### Usage
```tsx
import {Avatar} from "@thenamespace/uikit";
export function Basic() {
return (
JD
B
JR
);
}
```
### Anatomy
Import the Avatar component and access all parts using dot notation.
```tsx
import { Avatar } from "@thenamespace/uikit";
export default () => (
);
```
### Sizes
```tsx
import {Avatar} from "@thenamespace/uikit";
export function Sizes() {
return (
SM
MD
LG
);
}
```
### Colors
```tsx
import {Avatar} from "@thenamespace/uikit";
export function Colors() {
return (
DF
AC
SC
WR
DG
);
}
```
### Variants
```tsx
import { Avatar, Separator } from "@thenamespace/uikit";
import { UserIcon, HugeiconsIcon } from "@thenamespace/uikit/icons";
export function Variants() {
const colors = ["accent", "default", "success", "warning", "danger"] as const;
const variants = [
{ content: "AG", label: "letter", type: "letter" },
{ content: "AG", label: "letter soft", type: "letter-soft" },
{ content:
JD
);
}
```
## Styling
### Passing Tailwind CSS classes
```tsx
import { Avatar } from "@thenamespace/uikit";
function CustomAvatar() {
return (
XL
);
}
```
### Customizing the component classes
To customize the Avatar component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.avatar {
@apply size-16 border-2 border-primary;
}
.avatar__fallback {
@apply bg-gradient-to-br from-purple-500 to-pink-500;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The Avatar component uses these CSS classes:
#### Base Classes
- `.avatar` - Base container with default size (size-10)
- `.avatar__image` - Image element with aspect-square sizing
- `.avatar__fallback` - Fallback container with centered content
#### Size Modifiers
- `.avatar--sm` - Small avatar (size-8)
- `.avatar--md` - Medium avatar (default, no additional styles)
- `.avatar--lg` - Large avatar (size-12)
#### Variant Modifiers
- `.avatar--soft` - Soft variant with lighter background
#### Color Modifiers
- `.avatar__fallback--default` - Default text color
- `.avatar__fallback--accent` - Accent text color
- `.avatar__fallback--success` - Success text color
- `.avatar__fallback--warning` - Warning text color
- `.avatar__fallback--danger` - Danger text color
## API Reference
### Avatar Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------- | ----------- | ---------------------- |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Avatar size |
| `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Fallback color theme |
| `variant` | `'default' \| 'soft'` | `'default'` | Visual style variant |
| `className` | `string` | - | Additional CSS classes |
### Avatar.Image Props
| Prop | Type | Default | Description |
| ------------- | --------------------------------------------------- | ------- | -------------------------------------------------- |
| `src` | `string` | - | Image source URL |
| `srcSet` | `string` | - | The image `srcset` attribute for responsive images |
| `sizes` | `string` | - | The image `sizes` attribute for responsive images |
| `alt` | `string` | - | Alternative text for the image |
| `asChild` | `boolean` | `false` | Merge props onto the child element (e.g. `next/image`) instead of rendering a native `img` |
| `onLoad` | `(event: SyntheticEvent) => void` | - | Callback when the image loads successfully |
| `onError` | `(event: SyntheticEvent) => void` | - | Callback when there's an error loading the image |
| `crossOrigin` | `'anonymous' \| 'use-credentials'` | - | CORS setting for the image request |
| `loading` | `'eager' \| 'lazy'` | - | Native lazy loading attribute |
| `className` | `string` | - | Additional CSS classes |
### Avatar.Fallback Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------- | ------- | ---------------------------------------------- |
| `delayMs` | `number` | - | Delay before showing fallback (prevents flash) |
| `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | - | Override color from parent |
| `className` | `string` | - | Additional CSS classes |
# Badge
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/badge
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/badge.mdx
> Displays a small indicator positioned relative to another element, commonly used for notification counts, status dots, and labels
## Import
```tsx
import { Badge } from "@thenamespace/uikit";
```
## Anatomy
Badge is designed to be positioned relative to another element using `Badge.Anchor`. Plain-text children are automatically wrapped in ``.
> For standalone label usage, use the [Chip](/docs/components/chip) component instead.
```tsx
5
```
### Usage
```tsx
import {Avatar, Badge} from "@thenamespace/uikit";
const GREEN_AVATAR_URL = "/assets/avatars/green.jpg";
const ORANGE_AVATAR_URL =
"/assets/avatars/orange.jpg";
const BLUE_AVATAR_URL = "/assets/avatars/blue.jpg";
export function BadgeBasic() {
return (
JD
5
AB
New
CD
);
}
```
### Colors
```tsx
import {Avatar, Badge} from "@thenamespace/uikit";
const AVATAR_URL = "/assets/avatars/green.jpg";
export function BadgeColors() {
const colors = ["default", "accent", "success", "warning", "danger"] as const;
return (
JD
5
JD
New
JD
99+
JD
);
}
```
### Dot Badge
Empty badges act as status indicators — useful for online/offline states or activity signals.
```tsx
import {Avatar, Badge} from "@thenamespace/uikit";
const AVATAR_URL = "/assets/avatars/green.jpg";
export function BadgeDot() {
const colors = ["accent", "success", "warning", "danger"] as const;
return (
99+
);
}
```
### Customizing the component classes
To customize the Badge component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.badge {
@apply rounded-full text-xs;
}
.badge__label {
@apply font-semibold;
}
.badge--accent {
@apply shadow-sm;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The Badge component uses these CSS classes:
#### Base Classes
- `.badge` - Base badge container styles
- `.badge__label` - Label text slot styles
- `.badge-anchor` - Positioning wrapper for the anchored element
#### Color Classes
- `.badge--accent` - Accent color variant
- `.badge--danger` - Danger color variant
- `.badge--default` - Default color variant
- `.badge--success` - Success color variant
- `.badge--warning` - Warning color variant
#### Variant Classes
- `.badge--primary` - Primary variant with filled background
- `.badge--secondary` - Secondary variant with default background
- `.badge--soft` - Soft variant with lighter background
#### Size Classes
- `.badge--sm` - Small size
- `.badge--md` - Medium size (default)
- `.badge--lg` - Large size
#### Placement Classes
- `.badge--top-right` - Position at top-right corner (default)
- `.badge--top-left` - Position at top-left corner
- `.badge--bottom-right` - Position at bottom-right corner
- `.badge--bottom-left` - Position at bottom-left corner
#### Compound Variant Classes
Badges support combining variant and color classes (e.g., `.badge--primary.badge--accent`). The following combinations have default styles defined:
**Primary Variants:**
- `.badge--primary.badge--accent` - Primary accent with filled background
- `.badge--primary.badge--default` - Primary default with filled background
- `.badge--primary.badge--success` - Primary success with filled background
- `.badge--primary.badge--warning` - Primary warning with filled background
- `.badge--primary.badge--danger` - Primary danger with filled background
**Soft Variants:**
- `.badge--soft.badge--accent` - Soft accent with lighter background
- `.badge--soft.badge--default` - Soft default with lighter background
- `.badge--soft.badge--success` - Soft success with lighter background
- `.badge--soft.badge--warning` - Soft warning with lighter background
- `.badge--soft.badge--danger` - Soft danger with lighter background
## API Reference
### Badge Props
| Prop | Type | Default | Description |
| ----------- | -------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | - | Content to display inside the badge (text, number, or icon). When omitted, renders as a dot. |
| `className` | `string` | - | Additional CSS classes for the root element |
| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Color variant of the badge |
| `variant` | `"primary" \| "secondary" \| "soft"` | `"primary"` | Visual style variant |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the badge |
| `placement` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"top-right"` | Position of the badge relative to its anchor |
### Badge.Anchor Props
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | --------------------------------------------------------- |
| `children` | `React.ReactNode` | - | The element to anchor the badge to, plus the Badge itself |
| `className` | `string` | - | Additional CSS classes for the anchor wrapper |
### Badge.Label Props
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ----------------------------------------- |
| `children` | `React.ReactNode` | - | Label text content |
| `className` | `string` | - | Additional CSS classes for the label slot |
# Bar Chart
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/bar-chart
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/bar-chart.mdx
> A bar chart for comparing categorical data with grouped, stacked, and horizontal layout support.
## Usage
{/* DEMO bar-chart-default */}
```tsx
"use client";
import { BarChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
import { ChartTooltip } from "@thenamespace/uikit/chart-tooltip";
import { Chip } from "@thenamespace/uikit/chip";
import { ArrowUp02Icon, Icon } from "@thenamespace/uikit/icons";
const sales = [18, 32, 28, 45, 38, 52, 42, 55, 48, 60, 53, 58].map((value, index) => ({
month:
["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"][index] ??
"Unknown",
sales: value,
}));
export const DemoDefaultExample = () => (
Daily Sales
Units sold per month
!active || !payload?.length ? null : (
{label}
{payload.map((entry) => (
{entry.name ?? "Sales"}
{entry.value} units
))}
)
}
/>
);
```
## Anatomy
Import the BarChart component and access all parts using dot notation.
```tsx
import { BarChart } from "@thenamespace/uikit";
;
```
## Comparison
{/* DEMO bar-chart-comparison */}
```tsx
"use client";
import { BarChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
function Legend({
items,
}: {
items: ReadonlyArray<{ color: string; label: string }>;
}) {
return (
Weekly Orders
This week vs last week
);
};
```
## Custom Tooltip
{/* DEMO bar-chart-custom-tooltip */}
```tsx
"use client";
import { BarChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
import { ChartTooltip } from "@thenamespace/uikit/chart-tooltip";
const channels = [
{ direct: 3200, month: "Jan", online: 4200, retail: 2800 },
{ direct: 4100, month: "Feb", online: 5800, retail: 3400 },
{ direct: 3800, month: "Mar", online: 4900, retail: 3100 },
{ direct: 5200, month: "Apr", online: 7200, retail: 4200 },
{ direct: 4600, month: "May", online: 6100, retail: 3800 },
{ direct: 5800, month: "Jun", online: 8400, retail: 4500 },
];
const channelSeries = [
{ color: "var(--chart-3)", key: "online", label: "Online" },
{ color: "var(--chart-2)", key: "retail", label: "Retail" },
{ color: "var(--chart-1)", key: "direct", label: "Direct" },
] as const;
export const DemoCustomTooltipExample = () => (
Revenue by Channel
`${(value / 1000).toFixed(0)}k`}
width={40}
/>
{channelSeries.map((series) => (
{
if (
!active ||
!payload?.length ||
!payload.every((entry) => typeof entry.value === "number")
)
return null;
const total = payload.reduce(
(sum, entry) => sum + Number(entry.value ?? 0),
0,
);
return (
{label}
{payload.map((entry, index) => (
{entry.name}
${Number(entry.value).toLocaleString()}
))}
);
}}
/>
);
```
## Grouped
{/* DEMO bar-chart-grouped */}
```tsx
"use client";
import { BarChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
const channels = [
{ direct: 3200, month: "Jan", online: 4200, retail: 2800 },
{ direct: 4100, month: "Feb", online: 5800, retail: 3400 },
{ direct: 3800, month: "Mar", online: 4900, retail: 3100 },
{ direct: 5200, month: "Apr", online: 7200, retail: 4200 },
{ direct: 4600, month: "May", online: 6100, retail: 3800 },
{ direct: 5800, month: "Jun", online: 8400, retail: 4500 },
];
function Legend({
items,
}: {
items: ReadonlyArray<{ color: string; label: string }>;
}) {
return (
Revenue by Channel
`${(value / 1000).toFixed(0)}k`}
width={40}
/>
{channelSeries.map((series) => (
`${Number(value).toLocaleString()}`}
/>
}
/>
);
```
## Horizontal
{/* DEMO bar-chart-horizontal */}
```tsx
"use client";
import { BarChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
export const DemoHorizontalExample = () => (
Top Products
Units sold this quarter
);
```
## Horizontal Stacked
{/* DEMO bar-chart-horizontal-stacked */}
```tsx
"use client";
import { BarChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
function Legend({
items,
}: {
items: ReadonlyArray<{ color: string; label: string }>;
}) {
return (
Avg. Energy Activity
`${value} kcal`}
/>
}
/>
);
```
## KPIWith Bar Chart
{/* DEMO bar-chart-kpiwith-bar-chart */}
```tsx
"use client";
import { BarChart } from "@thenamespace/uikit";
import { KPI } from "@thenamespace/uikit/kpi";
import { TrendChip } from "@thenamespace/uikit/trend-chip";
const sales = [18, 32, 28, 45, 38, 52, 42, 55, 48, 60, 53, 58].map((value, index) => ({
month:
["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"][index] ??
"Unknown",
sales: value,
}));
export const DemoKPIWithBarChartExample = () => (
Monthly Sales
3.3%
last 30d
);
```
## Stacked
{/* DEMO bar-chart-stacked */}
```tsx
"use client";
import { BarChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
function Legend({
items,
}: {
items: ReadonlyArray<{ color: string; label: string }>;
}) {
return (
Revenue by Plan
`${(value / 1000).toFixed(0)}k`}
width={40}
/>
`${Number(value).toLocaleString()}`}
/>
}
/>
);
```
## CSS Classes
### Element Classes
- `.bar-chart` — Root container wrapping `ResponsiveContainer` and the Recharts chart.
### Recharts Theming
The following CSS rules target Recharts internal class names to apply Namespace UIKit design tokens automatically:
- `.bar-chart .recharts-cartesian-axis-tick-value` — Axis tick labels. 10px muted text.
- `.bar-chart .recharts-cartesian-axis-line` — Axis lines. Hidden by default.
- `.bar-chart .recharts-cartesian-axis-tick-line` — Tick lines. Hidden by default.
- `.bar-chart .recharts-cartesian-grid line` — Cartesian grid lines. Muted stroke at 0.15 opacity.
- `.bar-chart .recharts-tooltip-cursor` — Tooltip cursor. Subtle filled rectangle behind the hovered bar.
## API Reference
### BarChart
The root wrapper. Renders a `ResponsiveContainer` + Recharts `BarChart` with Namespace UIKit CSS theming applied automatically.
| Prop | Type | Default | Description |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------- |
| `data` | `Record[]` | — | Chart data — array of objects with numeric/string fields for each series. |
| `height` | `number` | `300` | Chart height in pixels. |
| `width` | ``number \| `${number}%` `` | `"100%"` | Chart width in pixels or percentage string. |
| `layout` | `"horizontal" \| "vertical"` | `"horizontal"` | Bar layout direction. Use `"vertical"` for horizontal bar charts. |
| `margin` | `{ top?: number; right?: number; bottom?: number; left?: number }` | `{ top: 8, right: 8, bottom: 0, left: 0 }` | Recharts margin around the chart area. |
| `children` | `ReactNode` | — | Recharts child components (`BarChart.Bar`, `BarChart.XAxis`, etc.). |
Also supports all native `div` HTML attributes.
### BarChart.Bar
Re-exported Recharts `Bar` component. Follows the [Recharts Bar API](https://recharts.github.io/en-US/api/Bar/).
### BarChart.XAxis
Re-exported Recharts `XAxis` component. Follows the [Recharts XAxis API](https://recharts.github.io/en-US/api/XAxis/).
### BarChart.YAxis
Re-exported Recharts `YAxis` component. Follows the [Recharts YAxis API](https://recharts.github.io/en-US/api/YAxis/).
### BarChart.Grid
Re-exported Recharts `CartesianGrid` component. Follows the [Recharts CartesianGrid API](https://recharts.github.io/en-US/api/CartesianGrid/).
### BarChart.Tooltip
Re-exported Recharts `Tooltip` component. Follows the [Recharts Tooltip API](https://recharts.github.io/en-US/api/Tooltip/). Use with `BarChart.TooltipContent` for styled tooltips.
### BarChart.TooltipContent
Pre-built tooltip renderer for Recharts. Pass as the `content` prop of `BarChart.Tooltip`. See [ChartTooltip](/react/components/chart-tooltip) for full props.
# Breadcrumbs
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/breadcrumbs
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/breadcrumbs.mdx
> Navigation breadcrumbs showing the current page's location within a hierarchy
## Import
```tsx
import { Breadcrumbs } from "@thenamespace/uikit";
```
### Usage
```tsx
"use client";
import {Breadcrumbs} from "@thenamespace/uikit";
export default function BreadcrumbsBasic() {
return (
Home
Products
Electronics
Laptop
);
}
```
### Anatomy
Import the Breadcrumbs component and access all parts using dot notation.
```tsx
import { Breadcrumbs } from "@thenamespace/uikit";
export default () => (
Home
Category
Current Page
);
```
### Navigation Levels
```tsx
"use client";
import {Breadcrumbs} from "@thenamespace/uikit";
export default function BreadcrumbsLevel2() {
return (
Home
Current Page
);
}
```
```tsx
"use client";
import {Breadcrumbs} from "@thenamespace/uikit";
export default function BreadcrumbsLevel3() {
return (
Home
Category
Current Page
);
}
```
### Custom Separator
```tsx
"use client";
import {Breadcrumbs} from "@thenamespace/uikit";
export default function BreadcrumbsCustomSeparator() {
return (
Home
Products
Electronics
Laptop
);
}
```
### Disabled State
```tsx
"use client";
import {Breadcrumbs} from "@thenamespace/uikit";
export default function BreadcrumbsDisabled() {
return (
Home
Products
Electronics
Laptop
);
}
```
### Custom Render Function
```tsx
"use client";
import {Breadcrumbs} from "@thenamespace/uikit";
export function CustomRenderFunction() {
return (
}>
Home
}>
Products
}>
Electronics
}>
Laptop
);
}
```
## Styling
### Passing Tailwind CSS classes
```tsx
import { Breadcrumbs } from "@thenamespace/uikit";
function CustomBreadcrumbs() {
return (
Home
Current
);
}
```
### Customizing the component classes
To customize the Breadcrumbs component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.breadcrumbs {
@apply gap-4 text-lg;
}
.breadcrumbs__link {
@apply font-semibold;
}
.breadcrumbs__separator {
@apply text-blue-500;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The Breadcrumbs component uses these CSS classes:
#### Base Classes
- `.breadcrumbs` - Base breadcrumbs container
- `.breadcrumbs__item` - Individual breadcrumb item wrapper
- `.breadcrumbs__link` - Breadcrumb link element
- `.breadcrumbs__separator` - Separator icon between items
#### State Classes
- `.breadcrumbs__link[data-current="true"]` - Current page indicator (not a link)
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
- **Current**: `[data-current="true"]` on link (indicates current page)
- **Hover**: Link elements support standard hover states
- **Disabled**: `isDisabled` prop disables all links
## API Reference
### Breadcrumbs Props
| Prop | Type | Default | Description |
| ------------ | ----------------------------------------------------------------- | ------------------ | --------------------------------------------------------------- |
| `separator` | `ReactNode` | chevron-right icon | Custom separator between breadcrumb items |
| `isDisabled` | `boolean` | `false` | Whether all breadcrumb links are disabled |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode` | - | The breadcrumb items |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function |
### Breadcrumbs.Item Props
| Prop | Type | Default | Description |
| ----------- | ----------------------------------------------------------------------------- | ------- | --------------------------------------------------------------- |
| `href` | `string` | - | The URL to link to (omit for current page) |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Item content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function |
## Accessibility
Breadcrumbs uses React Aria Components' Breadcrumbs primitive, which provides:
- Proper ARIA attributes for navigation landmarks
- Current page indication via `aria-current="page"`
- Keyboard navigation support
- Screen reader announcements for navigation context
The last breadcrumb item (without `href`) automatically becomes the current page indicator.
# ButtonGroup
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/button-group
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/button-group.mdx
> Group related buttons together with consistent styling and spacing
## Import
```tsx
import { ButtonGroup, Button } from "@thenamespace/uikit";
```
### Usage
```tsx
import {
Button,
ButtonGroup,
Chip,
Description,
Dropdown,
Label,
} from "@thenamespace/uikit";
import {
ArrowDown01Icon,
ArrowLeft01Icon,
ArrowRight01Icon,
GitForkIcon,
MoreHorizontalIcon,
Image01Icon,
PinIcon,
QrCodeIcon,
StarIcon,
TextAlignCenterIcon,
TextAlignJustifyCenterIcon,
TextAlignLeftIcon,
TextAlignRightIcon,
ThumbsDownIcon,
ThumbsUpIcon,
Video01Icon,
HugeiconsIcon,
} from "@thenamespace/uikit/icons";
export function Basic() {
return (
);
```
> **ButtonGroup** wraps multiple Button components together, applying consistent styling, spacing, and automatic border radius handling. It uses React Context to pass `size`, `variant`, and `isDisabled` props to all child buttons.
### Variants
```tsx
import {Button, ButtonGroup} from "@thenamespace/uikit";
export function Variants() {
return (
);
}
```
### Sizes
```tsx
import {Button, ButtonGroup} from "@thenamespace/uikit";
export function Sizes() {
return (
);
}
```
### Orientation
Use the `orientation` prop to arrange buttons horizontally or vertically.
```tsx
import { Button, ButtonGroup } from "@thenamespace/uikit";
import {
TextAlignCenterIcon,
TextAlignJustifyCenterIcon,
TextAlignLeftIcon,
TextAlignRightIcon,
HugeiconsIcon,
} from "@thenamespace/uikit/icons";
export function Orientation() {
return (
);
}
```
### With Icons
```tsx
import { Button, ButtonGroup } from "@thenamespace/uikit";
import {
Globe02Icon,
Add01Icon,
Delete02Icon,
HugeiconsIcon,
} from "@thenamespace/uikit/icons";
export function WithIcons() {
return (
);
}
```
### Full Width
```tsx
import { Button, ButtonGroup } from "@thenamespace/uikit";
import {
TextAlignCenterIcon,
TextAlignLeftIcon,
TextAlignRightIcon,
HugeiconsIcon,
} from "@thenamespace/uikit/icons";
export function FullWidth() {
return (
);
}
```
### Disabled State
```tsx
import {Button, ButtonGroup} from "@thenamespace/uikit";
export function Disabled() {
return (
);
}
```
### Without Separator
Simply omit the `
);
}
```
## Styling
### Passing Tailwind CSS classes
```tsx
import { ButtonGroup, Button } from "@thenamespace/uikit";
function CustomButtonGroup() {
return (
);
}
```
### Customizing the component classes
To customize the ButtonGroup component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.button-group {
@apply gap-2 rounded-lg;
}
.button-group__separator {
@apply opacity-25;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ButtonGroup component uses these CSS classes:
#### Base Classes
- `.button-group` - Base button group container
- `.button-group--full-width` - Full width modifier
- `.button-group__separator` - Separator element between buttons
The ButtonGroup component automatically applies border radius to buttons:
- First button gets rounded left/start edge
- Last button gets rounded right/end edge
- Middle buttons have no border radius
- Single button gets full border radius on all edges
Add `
# Button
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/button
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/button.mdx
> A clickable button component with multiple variants and states
## Import
```tsx
import { Button } from "@thenamespace/uikit";
```
### Usage
```tsx
"use client";
import {Button} from "@thenamespace/uikit";
export function Basic() {
return ;
}
```
### Variants
```tsx
import {Button} from "@thenamespace/uikit";
export function Variants() {
return (
);
}
```
### With Icons
```tsx
import { Button } from "@thenamespace/uikit";
import {
Mail01Icon,
Globe02Icon,
Add01Icon,
Delete02Icon,
HugeiconsIcon,
} from "@thenamespace/uikit/icons";
export function WithIcons() {
return (
);
}
```
### Icon Only
```tsx
import { Button } from "@thenamespace/uikit";
import {
MoreHorizontalIcon,
Settings01Icon,
Delete02Icon,
HugeiconsIcon,
} from "@thenamespace/uikit/icons";
export function IconOnly() {
return (
);
}
```
### Loading
```tsx
"use client";
import {Button, Spinner} from "@thenamespace/uikit";
import React from "react";
export function Loading() {
return (
);
}
```
### Loading State
```tsx
"use client";
import React, { useState } from "react";
import { Button, Spinner } from "@thenamespace/uikit";
import { Attachment01Icon, HugeiconsIcon } from "@thenamespace/uikit/icons";
export function LoadingState() {
const [isLoading, setLoading] = useState(false);
const handlePress = () => {
setLoading(true);
setTimeout(() => setLoading(false), 2000);
};
return (
);
}
```
### Sizes
```tsx
import {Button} from "@thenamespace/uikit";
export function Sizes() {
return (
);
}
```
### Full Width
```tsx
import { Button } from "@thenamespace/uikit";
import { Add01Icon, HugeiconsIcon } from "@thenamespace/uikit/icons";
export function FullWidth() {
return (
);
}
```
### Disabled State
```tsx
import {Button} from "@thenamespace/uikit";
export function Disabled() {
return (
);
}
```
### Social Buttons
```tsx
import { Button } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
export function Social() {
return (
);
}
```
### Custom Render Function
```tsx
"use client";
import {Button} from "@thenamespace/uikit";
export function CustomRenderFunction() {
return (
);
}
```
## Styling
### Passing Tailwind CSS classes
```tsx
import { Button } from "@thenamespace/uikit";
function CustomButton() {
return (
);
}
```
### Customizing the component classes
To customize the Button component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.button {
@apply bg-purple-500 text-white hover:bg-purple-600;
}
.button--icon-only {
@apply rounded-lg bg-blue-500;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### Adding custom variants
You can extend Namespace UIKit components by wrapping them and adding your own custom variants.
```tsx
import type {ButtonProps} from "@thenamespace/uikit";
import type {VariantProps} from "tailwind-variants";
import {Button, buttonVariants} from "@thenamespace/uikit";
import {tv} from "tailwind-variants";
const myButtonVariants = tv({
base: "text-md font-semibold shadow-md text-shadow-lg data-[pending=true]:opacity-40",
defaultVariants: {
radius: "full",
variant: "primary",
},
extend: buttonVariants,
variants: {
radius: {
full: "rounded-full",
lg: "rounded-lg",
md: "rounded-md",
sm: "rounded-sm",
},
size: {
lg: "h-12 px-8",
md: "h-11 px-6",
sm: "h-10 px-4",
xl: "h-13 px-10",
},
variant: {
primary: "text-white dark:bg-white/10 dark:text-white dark:hover:bg-white/15",
},
},
});
type MyButtonVariants = VariantProps;
export type MyButtonProps = Omit &
MyButtonVariants & {className?: string};
function CustomButton({className, radius, variant, ...props}: MyButtonProps) {
return ;
}
export function CustomVariants() {
return Custom Button ;
}
```
### Adding Ripple Effect
The Button component supports ripple effects through composition, allowing you to nest ripple components as children. This example uses [m3-ripple](https://github.com/saltyaom/m3-ripple).
```tsx
"use client";
import {Button} from "@thenamespace/uikit";
import {Ripple} from "m3-ripple";
import "m3-ripple/ripple.css";
export function RippleEffect() {
return (
);
}
```
### CSS Classes
The Button component uses these CSS classes:
#### Base & Size Classes
- `.button` - Base button styles
- `.button--sm` - Small size variant
- `.button--md` - Medium size variant
- `.button--lg` - Large size variant
#### Variant Classes
- `.button--primary`
- `.button--secondary`
- `.button--tertiary`
- `.button--outline`
- `.button--ghost`
- `.button--danger`
#### Modifier Classes
- `.button--icon-only`
- `.button--icon-only.button--sm`
- `.button--icon-only.button--lg`
### Interactive States
The button supports both CSS pseudo-classes and data attributes for flexibility:
- **Hover**: `:hover` or `[data-hovered="true"]`
- **Active/Pressed**: `:active` or `[data-pressed="true"]` (includes scale transform)
- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring)
- **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events)
- **Pending**: `[data-pending]` (no pointer events during loading)
## API Reference
### Button Props
| Prop | Type | Default | Description |
| ------------ | ---------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------- |
| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the button |
| `fullWidth` | `boolean` | `false` | Whether the button should take full width of its container |
| `isDisabled` | `boolean` | `false` | Whether the button is disabled |
| `isPending` | `boolean` | `false` | Whether the button is in a loading state |
| `isIconOnly` | `boolean` | `false` | Whether the button contains only an icon |
| `onPress` | `(e: PressEvent) => void` | - | Handler called when the button is pressed |
| `children` | `React.ReactNode \| (values: ButtonRenderProps) => React.ReactNode` | - | Button content or render prop |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ButtonRenderProps
When using the render prop pattern, these values are provided:
| Prop | Type | Description |
| ---------------- | --------- | ---------------------------------------------- |
| `isPending` | `boolean` | Whether the button is in a loading state |
| `isPressed` | `boolean` | Whether the button is currently pressed |
| `isHovered` | `boolean` | Whether the button is hovered |
| `isFocused` | `boolean` | Whether the button is focused |
| `isFocusVisible` | `boolean` | Whether the button should show focus indicator |
| `isDisabled` | `boolean` | Whether the button is disabled |
# Calendar Year Picker
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/calendar-year-picker
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/calendar-year-picker.mdx
> Year-selection parts shared by Calendar and RangeCalendar.
Import this public entry point directly when composing lower-level UIKit parts.
```tsx
import * as CalendarYearPicker from "@thenamespace/uikit/calendar-year-picker";
```
See [calendar](./calendar) for complete composition examples and API guidance.
This entry point is also re-exported from `@thenamespace/uikit`. Direct imports make the dependency explicit and provide a stable location for advanced customization.
# Calendar
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/calendar
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/calendar.mdx
> Composable date picker with month grid, navigation, and year picker support built on React Aria Calendar
## Import
```tsx
import { Calendar } from "@thenamespace/uikit";
```
### Usage
```tsx
"use client";
import {Calendar} from "@thenamespace/uikit";
export function Basic() {
return (
{(day) => {day} }
{(date) =>
);
}
```
### Anatomy
```tsx
import { Calendar } from "@thenamespace/uikit";
export default () => (
{(day) => {day} }
{(date) =>
);
```
### Year Picker
`Calendar.YearPickerTrigger`, `Calendar.YearPickerGrid`, and their body/cell subcomponents provide an integrated year navigation pattern.
```tsx
"use client";
import {Calendar} from "@thenamespace/uikit";
export function YearPicker() {
return (
{(day) => {day} }
{(date) =>
{({year}) =>
);
}
```
### Default Value
```tsx
"use client";
import {Calendar} from "@thenamespace/uikit";
import {parseDate} from "@internationalized/date";
export function DefaultValue() {
return (
{(day) => {day} }
{(date) =>
);
}
```
### Controlled
Use controlled `value` and `focusedValue` for external state coordination and custom shortcuts.
```tsx
"use client";
import type {CalendarDate} from "@internationalized/date";
import {Button, ButtonGroup, Calendar, Description} from "@thenamespace/uikit";
import {
getLocalTimeZone,
parseDate,
startOfMonth,
startOfWeek,
today,
} from "@internationalized/date";
import {useState} from "react";
import {useLocale} from "react-aria-components";
export function Controlled() {
const [value, setValue] = useState(null);
const [focusedDate, setFocusedDate] = useState(parseDate("2025-12-25"));
const {locale} = useLocale();
return (
{(day) => {day} }
{(date) =>
Selected date: {value ? value.toString() : "(none)"}
);
}
```
### Min and Max Dates
```tsx
"use client";
import {Calendar, Description} from "@thenamespace/uikit";
import {getLocalTimeZone, today} from "@internationalized/date";
export function MinMaxDates() {
const now = today(getLocalTimeZone());
const minDate = now;
const maxDate = now.add({months: 3});
return (
{(day) => {day} }
{(date) =>
Select a date between today and {maxDate.toString()}
);
}
```
### Unavailable Dates
Use `isDateUnavailable` to block dates such as weekends, holidays, or booked slots.
```tsx
"use client";
import type {DateValue} from "@internationalized/date";
import {Calendar, Description} from "@thenamespace/uikit";
import {isWeekend} from "@internationalized/date";
import {useLocale} from "react-aria-components";
export function UnavailableDates() {
const {locale} = useLocale();
const isDateUnavailable = (date: DateValue) => isWeekend(date, locale);
return (
{(day) => {day} }
{(date) =>
Weekends are unavailable
);
}
```
### Weeks in Month
Set `weeksInMonth` to a fixed value (for example, `6`) to keep the grid height stable when navigating between months. Use with care in non-Gregorian locales, similar to `firstDayOfWeek`.
```tsx
"use client";
import {Calendar, Description} from "@thenamespace/uikit";
export function WeeksInMonth() {
return (
{(day) => {day} }
{(date) =>
Always shows 6 weeks per month to avoid layout shift when navigating
);
}
```
### Week View
Set `visibleDuration={{ weeks: n }}` to show one or more weeks at a time. Navigation advances by the visible week range. Use `pageBehavior="single"` to move one week at a time when showing multiple weeks.
```tsx
"use client";
import {Calendar, Label, ListBox, Select} from "@thenamespace/uikit";
import {useState} from "react";
const weekOptions = [
{id: "1", name: "1 week"},
{id: "2", name: "2 weeks"},
{id: "3", name: "3 weeks"},
{id: "4", name: "4 weeks"},
{id: "5", name: "5 weeks"},
{id: "6", name: "6 weeks"},
{id: "8", name: "8 weeks"},
] as const;
export function WeekView() {
const [weeks, setWeeks] = useState(1);
return (
{(day) => {day} }
{(date) =>
);
}
```
### Day View
Set `visibleDuration={{ days: n }}` to show a rolling window of consecutive days. Navigation advances by the visible day range. Use `pageBehavior="single"` to move one day at a time when showing multiple days.
```tsx
"use client";
import {Calendar, Label, ListBox, Select} from "@thenamespace/uikit";
import {useState} from "react";
const dayOptions = [
{id: "1", name: "1 day"},
{id: "5", name: "5 days"},
{id: "7", name: "7 days"},
{id: "8", name: "8 days"},
{id: "10", name: "10 days"},
{id: "14", name: "14 days"},
{id: "21", name: "21 days"},
] as const;
export function DayView() {
const [days, setDays] = useState(5);
return (
{(day) => {day} }
{(date) =>
);
}
```
### Multiple Selection
Set `selectionMode="multiple"` to let users select several dates. `value`, `defaultValue`, and `onChange` use an array of dates.
```tsx
"use client";
import type {DateValue} from "@internationalized/date";
import {Calendar, Description} from "@thenamespace/uikit";
import {useState} from "react";
export function MultipleSelection() {
const [value, setValue] = useState([]);
return (
{(day) => {day} }
{(date) =>
{value?.length ? `${value.length} date(s) selected` : "Select multiple dates"}
);
}
```
### Disabled
```tsx
"use client";
import {Calendar, Description} from "@thenamespace/uikit";
import {getLocalTimeZone, today} from "@internationalized/date";
export function Disabled() {
return (
{(day) => {day} }
{(date) =>
Calendar is disabled
);
}
```
### Read Only
```tsx
"use client";
import {Calendar, Description} from "@thenamespace/uikit";
import {getLocalTimeZone, today} from "@internationalized/date";
export function ReadOnly() {
return (
{(day) => {day} }
{(date) =>
Calendar is read-only
);
}
```
### Focused Value
Programmatically control which date is focused using `focusedValue` and `onFocusChange`.
```tsx
"use client";
import type {DateValue} from "@internationalized/date";
import {Button, Calendar, Description} from "@thenamespace/uikit";
import {parseDate} from "@internationalized/date";
import {useState} from "react";
export function FocusedValue() {
const [focusedDate, setFocusedDate] = useState(parseDate("2025-06-15"));
return (
{(day) => {day} }
{(date) =>
Focused: {focusedDate.toString()}
);
}
```
### Cell Indicators
You can customize `Calendar.Cell` children and use `Calendar.CellIndicator` to display metadata like events.
```tsx
"use client";
import {Calendar} from "@thenamespace/uikit";
import {getLocalTimeZone, isToday} from "@internationalized/date";
const datesWithEvents = [3, 7, 12, 15, 21, 28];
export function WithIndicators() {
return (
{(day) => {day} }
{(date) => (
{({formattedDate}) => (
<>
{formattedDate}
{(isToday(date, getLocalTimeZone()) || datesWithEvents.includes(date.day)) && (
)}
);
}
```
### Multiple Months
Render multiple grids with `visibleDuration` and `offset` for booking and planning experiences. Use `Calendar.Heading` with an `offset` (for example, `offset={{ months: 1 }}`) in each column header to label that month.
```tsx
"use client";
import {Calendar} from "@thenamespace/uikit";
export function MultipleMonths() {
return (
{(day) => {day} }
{(date) =>
{(day) => {day} }
{(date) =>
);
}
```
### International Calendars
By default, Calendar displays dates using the calendar system for the user's locale. You can override this by wrapping your Calendar with `I18nProvider` and setting the [Unicode calendar locale extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string).
The example below shows the Indian calendar system:
```tsx
"use client";
import {Calendar} from "@thenamespace/uikit";
import {getLocalTimeZone, today} from "@internationalized/date";
import {I18nProvider} from "react-aria-components";
export function InternationalCalendar() {
return (
{(day) => {day} }
{(date) =>
{({year}) =>
);
}
```
**Note:** The `onChange` event always returns a date in the same calendar system as the `value` or `defaultValue` (Gregorian if no value is provided), regardless of the displayed locale. This ensures your application logic works consistently with a single calendar system while still displaying dates in the user's preferred format.
### Custom Navigation Icons
Pass children to `Calendar.NavButton` to replace the default chevron icons.
```tsx
"use client";
import {Calendar} from "@thenamespace/uikit";
export function CustomIcons() {
return (
{(day) => {day} }
{(date) =>
);
}
```
### Real-World Example
```tsx
"use client";
import type {CalendarDate, DateValue} from "@internationalized/date";
import {Button, Calendar} from "@thenamespace/uikit";
import {getLocalTimeZone, isWeekend, today} from "@internationalized/date";
import {useState} from "react";
import {useLocale} from "react-aria-components";
export function BookingCalendar() {
const [selectedDate, setSelectedDate] = useState(null);
const {locale} = useLocale();
const bookedDates = [5, 6, 12, 13, 14, 20];
const isDateUnavailable = (date: DateValue) => {
return isWeekend(date, locale) || bookedDates.includes(date.day);
};
return (
{(day) => {day} }
{(date) => (
{({formattedDate, isUnavailable}) => (
<>
{formattedDate}
{!isUnavailable &&
!isWeekend(date, locale) &&
bookedDates.includes(date.day) &&
)}
);
}
```
### Custom Styles
```tsx
"use client";
import {Calendar} from "@thenamespace/uikit";
export function CustomStyles() {
return (
{(day) => {day} }
{(date) =>
{({year}) =>
);
}
```
## Styling
### Passing Tailwind CSS classes
```tsx
import { Calendar } from "@thenamespace/uikit";
function CustomCalendar() {
return (
{(day) => {day} }
{(date) =>
);
}
```
### Customizing the component classes
```css
@layer components {
.calendar {
@apply w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm;
}
.calendar__heading {
@apply text-sm font-semibold text-default-700;
}
.calendar__cell[data-selected="true"] {
@apply bg-accent text-accent-foreground;
}
}
```
### CSS Classes
Calendar uses these classes in `packages/styles/components/calendar.css` and `packages/styles/components/calendar-year-picker.css`:
- `.calendar` - Root container.
- `.calendar__header` - Header row containing nav buttons and heading.
- `.calendar__heading` - Current month label.
- `.calendar__nav-button` - Previous/next navigation controls.
- `.calendar__grid` - Main day grid.
- `.calendar__grid-header` - Weekday header row wrapper.
- `.calendar__grid-body` - Date rows wrapper.
- `.calendar__header-cell` - Weekday header cell.
- `.calendar__cell` - Interactive day cell.
- `.calendar__cell-indicator` - Dot indicator inside a day cell.
- `.calendar-year-picker__trigger` - Year picker toggle button.
- `.calendar-year-picker__trigger-heading` - Heading text inside year picker trigger.
- `.calendar-year-picker__trigger-indicator` - Indicator icon inside year picker trigger.
- `.calendar-year-picker__year-grid` - Overlay grid of selectable years.
- `.calendar-year-picker__year-cell` - Individual year option.
### Interactive States
Calendar supports both pseudo-classes and React Aria data attributes:
- **Selected**: `[data-selected="true"]`
- **Today**: `[data-today="true"]`
- **Unavailable**: `[data-unavailable="true"]`
- **Outside month**: `[data-outside-month="true"]`
- **Hovered**: `:hover` or `[data-hovered="true"]`
- **Pressed**: `:active` or `[data-pressed="true"]`
- **Focus visible**: `:focus-visible` or `[data-focus-visible="true"]`
- **Disabled**: `:disabled` or `[data-disabled="true"]`
## API Reference
### Calendar Props
Calendar inherits all props from React Aria [Calendar](https://react-spectrum.adobe.com/react-aria/Calendar.html).
| Prop | Type | Default | Description |
| ------------------------ | ---------------------------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `selectionMode` | `'single' \| 'multiple'` | `'single'` | Whether one or many dates can be selected. |
| `value` | `DateValue \| null` or `DateValue[] \| null` | - | Controlled selected date(s). Use an array when `selectionMode` is `multiple`. |
| `defaultValue` | `DateValue \| null` or `DateValue[] \| null` | - | Initial selected date(s) (uncontrolled). |
| `onChange` | `(value: DateValue \| null)` or `(value: DateValue[] \| null) => void` | - | Called when selection changes. |
| `focusedValue` | `DateValue` | - | Controlled focused date. |
| `onFocusChange` | `(value: DateValue) => void` | - | Called when focus moves to another date. |
| `minValue` | `DateValue` | Calendar-aware `1900-01-01` | Earliest selectable date. |
| `maxValue` | `DateValue` | Calendar-aware `2099-12-31` | Latest selectable date. |
| `weeksInMonth` | `number` | - | The number of weeks in a month. This overrides the default set by the locale. |
| `isDateUnavailable` | `(date: DateValue) => boolean` | - | Marks dates as unavailable. |
| `firstDayOfWeek` | `'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'` | - | Overrides the locale default for the first day of the week. |
| `pageBehavior` | `'visible' \| 'single'` | `'visible'` | Whether paging advances by the visible duration or one unit at a time. |
| `selectionAlignment` | `'start' \| 'center' \| 'end'` | `'center'` | Aligns the visible range to the selection on initial render. |
| `isDisabled` | `boolean` | `false` | Disables interaction and selection. |
| `isReadOnly` | `boolean` | `false` | Keeps content readable but prevents selection changes. |
| `isInvalid` | `boolean` | `false` | Marks the calendar as invalid for validation UI. |
| `visibleDuration` | `{months?: number; weeks?: number; days?: number}` | `{months: 1}` | Visible time range. Use `{ months: n }` for month view, `{ weeks: n }` for week view, or `{ days: n }` for day view. |
| `defaultYearPickerOpen` | `boolean` | `false` | Initial open state of internal year picker. |
| `isYearPickerOpen` | `boolean` | - | Controlled year picker open state. |
| `onYearPickerOpenChange` | `(isOpen: boolean) => void` | - | Called when year picker open state changes. |
### Composition Parts
| Component | Description |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `Calendar.Header` | Header container for navigation and heading. |
| `Calendar.Heading` | Formatted heading for the visible range. Supports `offset` (for multi-month layouts) and `format` (month/year/day options). |
| `Calendar.NavButton` | Previous/next navigation control (`slot=\"previous\"` or `slot=\"next\"`). |
| `Calendar.Grid` | Day grid for one month (`offset` supported for multi-month layouts). |
| `Calendar.GridHeader` | Weekday header container. |
| `Calendar.GridBody` | Date cell body container. |
| `Calendar.HeaderCell` | Weekday label cell. |
| `Calendar.Cell` | Individual date cell. |
| `Calendar.CellIndicator` | Optional indicator element for custom metadata. |
| `Calendar.YearPickerTrigger` | Trigger to toggle year-picker mode. |
| `Calendar.YearPickerTriggerHeading` | Localized heading content inside the year-picker trigger. |
| `Calendar.YearPickerTriggerIndicator` | Toggle icon inside the year-picker trigger. |
| `Calendar.YearPickerGrid` | Overlay year selection grid container. |
| `Calendar.YearPickerGridBody` | Body renderer for year grid cells. |
| `Calendar.YearPickerCell` | Individual year option cell. |
### Year Picker Parts
Year picker subcomponents inherit formatting props from React Aria [`useCalendarHeading`](https://react-aria.adobe.com/useCalendar#usecalendarheading) and [`useCalendarYearPicker`](https://react-aria.adobe.com/useCalendar#usecalendaryearpicker).
| Component | Prop | Type | Default | Description |
| ----------------------------------- | -------------- | ---------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `Calendar.YearPickerTriggerHeading` | `format` | `DateFormatterOptions` | - | Customize month/year label (e.g. `{month: 'short'}`). |
| `Calendar.YearPickerTriggerHeading` | `offset` | `{months?: number}` | - | Shift the heading relative to the focused date (multi-month layouts). |
| `Calendar.YearPickerGrid` | `format` | `DateFormatterOptions` | `{year: 'numeric'}` | Customize year cell labels (era, calendar system, etc.). |
| `Calendar.YearPickerGrid` | `visibleYears` | `number` | min–max span or `20` | Number of years shown in the sliding window. Defaults to the full range between `minValue` and `maxValue` when both are set. |
### Calendar.Cell Render Props
When `Calendar.Cell` children is a function, React Aria render props are available:
| Prop | Type | Description |
| ---------------- | --------- | ------------------------------------------- |
| `formattedDate` | `string` | Localized day label for the cell. |
| `isSelected` | `boolean` | Whether the date is selected. |
| `isUnavailable` | `boolean` | Whether the date is unavailable. |
| `isDisabled` | `boolean` | Whether the cell is disabled. |
| `isOutsideMonth` | `boolean` | Whether the date belongs to adjacent month. |
For a complete list of supported calendar systems and their identifiers, see:
- [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
- [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)
### Related packages
- [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) and utilities used by all date components
- [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — override locale for a subtree
- [`useLocale`](https://react-aria.adobe.com/useLocale) — read the current locale and layout direction
# Card
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/card
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/card.mdx
> Flexible container component for grouping related content and actions
## Import
```tsx
import { Card } from "@thenamespace/uikit";
```
### Usage
```tsx
import { Card, Link } from "@thenamespace/uikit";
import { DollarCircleIcon, HugeiconsIcon } from "@thenamespace/uikit/icons";
export function Default() {
return (
Become an Acme Creator!
Visit the Acme Creator Hub to sign up today and start earning credits
from your fans and followers.
Creator Hub
);
}
```
### Anatomy
Import the Card component and access all parts using dot notation.
```tsx
import { Card } from "@thenamespace/uikit";
export default () => (
);
```
### Variants
Cards come in semantic variants that describe their prominence level rather than specific visual styles. This allows themes to interpret them differently:
```tsx
import {Card} from "@thenamespace/uikit";
export function Variants() {
return (
Transparent
Minimal prominence with transparent background
Default
Standard card appearance (bg-surface)
Secondary
Medium prominence (bg-surface-secondary)
Tertiary
Higher prominence (bg-surface-tertiary)
);
}
```
- **`transparent`** - Minimal prominence, transparent background (great for nested cards)
- **`default`** - Standard card for most use cases (surface-secondary)
- **`secondary`** - Medium prominence to draw moderate attention (surface-tertiary)
- **`tertiary`** - Higher prominence for important content (surface-tertiary)
### Horizontal Layout
```tsx
import {Button, Card, CloseButton} from "@thenamespace/uikit";
export function Horizontal() {
return (
Become an ACME Creator!
Lorem ipsum dolor sit amet consectetur. Sed arcu donec id aliquam dolor sed amet
faucibus etiam.
);
}
```
### With Avatar
```tsx
import {Avatar, Card} from "@thenamespace/uikit";
export function WithAvatar() {
return (
Indie Hackers
148 members
IH
By Martha
AI Builders
362 members
B
By John
);
}
```
### With Images
```tsx
import { Avatar, Button, Card, CloseButton, Link } from "@thenamespace/uikit";
import { DollarCircleIcon, HugeiconsIcon } from "@thenamespace/uikit/icons";
export function WithImages() {
return (
);
}
```
### With Form
```tsx
"use client";
import {Button, Card, Form, Input, Label, Link, TextField} from "@thenamespace/uikit";
export function WithForm() {
const onSubmit = (e: React.FormEvent) => {
e.preventDefault();
const formData = new FormData(e.currentTarget);
const data: Record = {};
// Convert FormData to plain object
formData.forEach((value, key) => {
data[key] = value.toString();
});
alert("Form submitted successfully!");
};
return (
Login
Enter your credentials to access your account
);
}
```
## Accessibility
```tsx
import { Card } from '@thenamespace/uikit';
import { cardVariants } from '@thenamespace/uikit/styles';
// Semantic markup
Article Title
// Interactive cards
Product Name
```
## Styling
### Component Customization
```tsx
Custom Styled Card
Custom colors applied
```
### CSS Variable Overrides
```css
/* Override specific variants */
.card--secondary {
@apply bg-gradient-to-br from-blue-50 to-purple-50;
}
/* Custom element styles */
.card__title {
@apply text-xl font-bold;
}
```
## CSS Classes
Card uses [BEM](https://getbem.com/) naming for predictable styling,:
#### Base Classes
- `.card` - Base container with padding and border
- `.card__header` - Header section container
- `.card__title` - Title with base font size and weight
- `.card__description` - Muted description text
- `.card__content` - Flexible content container
- `.card__footer` - Footer with row layout
#### Variant Classes
- `.card--transparent` - Minimal prominence, transparent background (maps to `transparent` variant)
- `.card--default` - Standard appearance with surface-secondary (default)
- `.card--secondary` - Medium prominence with surface-tertiary (maps to `secondary` variant)
- `.card--tertiary` - Higher prominence with surface-tertiary (maps to `tertiary` variant)
## API Reference
### Card
| Prop | Type | Default | Description |
| ----------- | --------------------------------------------------------- | ----------- | -------------------------------------------- |
| `variant` | `"transparent" \| "default" \| "secondary" \| "tertiary"` | `"default"` | Semantic variant indicating prominence level |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Card content |
### Card.Header
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Header content |
### Card.Title
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Title content (renders as `h3`) |
### Card.Description
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ------------------------------------ |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Description content (renders as `p`) |
### Card.Content
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Main content |
### Card.Footer
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | Footer content |
# Carousel
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/carousel
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/carousel.mdx
> A content browsing component for navigating through a collection of images or items, with thumbnails, dots, and navigation controls.
## Usage
{/* DEMO carousel-default */}
```tsx
"use client";
import { Carousel } from "@thenamespace/uikit";
const images = [
{
alt: "Sneakers front view",
src: "https://nextuipro.nyc3.cdn.digitaloceanspaces.com/components-images/shoes/product-view/1.jpeg",
},
{
alt: "Sneakers side view",
src: "https://nextuipro.nyc3.cdn.digitaloceanspaces.com/components-images/shoes/product-view/2.jpeg",
},
{
alt: "Sneakers back view",
src: "https://nextuipro.nyc3.cdn.digitaloceanspaces.com/components-images/shoes/product-view/3.jpeg",
},
{
alt: "Sneakers top view",
src: "https://nextuipro.nyc3.cdn.digitaloceanspaces.com/components-images/shoes/product-view/4.jpeg",
},
{
alt: "Sneakers detail view",
src: "https://nextuipro.nyc3.cdn.digitaloceanspaces.com/components-images/shoes/product-view/5.jpeg",
},
{
alt: "Sneakers sole view",
src: "https://nextuipro.nyc3.cdn.digitaloceanspaces.com/components-images/shoes/product-view/6.jpeg",
},
];
const ImageSlides = () => (
<>
{images.map((image) => (
))}
);
export const DemoDefaultExample = () => (
{images.map((image, index) => (
);
```
## Anatomy
Import the Carousel component and access all parts using dot notation.
```tsx
import { Carousel } from "@thenamespace/uikit";
;
```
## Modal Type
The modal type positions navigation arrows outside the content area, ideal for focused overlay-style viewing.
## Multiple Slides
{/* DEMO carousel-multiple-slides */}
```tsx
"use client";
import { Carousel } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
export const DemoMultipleSlidesExample = () => (
{Array.from({ length: 8 }, (_, index) => index + 1).map((number) => (
{number}
))}
);
```
Show multiple slides per viewport using Tailwind `basis` utility classes on `Carousel.Item`.
## Infinite Loop
{/* DEMO carousel-infinite-loop */}
```tsx
"use client";
import { Carousel } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
const NumberSlides = ({ count = 5 }: { count?: number }) => (
<>
{Array.from({ length: count }, (_, index) => index + 1).map((number) => (
{number}
))}
);
export const DemoInfiniteLoopExample = () => (
);
```
Enable infinite looping with `opts={{ loop: true }}`.
## Autoplay
{/* DEMO carousel-autoplay-story */}
```tsx
"use client";
import { useRef } from "react";
import { Carousel } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
import Autoplay from "embla-carousel-autoplay";
const NumberSlides = ({ count = 5 }: { count?: number }) => (
<>
{Array.from({ length: count }, (_, index) => index + 1).map((number) => (
{number}
))}
);
export const DemoAutoplayStoryExample = () => {
const plugin = useRef(Autoplay({ delay: 2000, stopOnInteraction: true }));
return (
);
};
```
Use the `embla-carousel-autoplay` plugin via the `plugins` prop.
## API Access
{/* DEMO carousel-api-access-story */}
```tsx
"use client";
import { useEffect, useState } from "react";
import { Carousel } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
import type { EmblaCarouselType } from "embla-carousel";
const NumberSlides = ({ count = 5 }: { count?: number }) => (
<>
{Array.from({ length: count }, (_, index) => index + 1).map((number) => (
{number}
))}
);
function ApiExample() {
const [api, setApi] = useState(),
[current, setCurrent] = useState(1),
[count, setCount] = useState(0);
useEffect(() => {
if (!api) return;
const update = () => {
setCurrent(api.selectedScrollSnap() + 1);
setCount(api.scrollSnapList().length);
};
update();
api.on("select", update).on("reInit", update);
return () => {
api.off("select", update).off("reInit", update);
};
}, [api]);
return (
);
}
export const DemoApiAccessStoryExample = () =>
))}
);
export const DemoModalTypeExample = () => (
{images.map((image, index) => (
);
```
## CSS Classes
### Base Classes
- `.carousel` — Root wrapper. Sets `--carousel-gap` for slide spacing.
- `.carousel__viewport-wrapper` — Relative positioning context for navigation buttons.
- `.carousel__viewport` — Overflow-hidden container that clips off-screen slides.
- `.carousel__content` — Flex container holding all slide items.
- `.carousel__item` — Individual slide. Min-width zero, flex-shrink zero, full basis by default.
### Type Modifier Classes
- `.carousel--in-place` — Default type. Navigation arrows positioned inside the viewport area.
- `.carousel--modal` — Overlay-style layout. Arrows positioned far outside the content, flex column with gap.
- `.carousel--miniatures` — Compact layout. Arrows inline with the thumbnail row.
### Navigation Button Classes
- `.carousel__previous` / `.carousel__next` — Absolute-positioned containers for Namespace UIKit Button (variant `tertiary`, size `sm`, icon-only).
- `.carousel__previous--in-place` / `.carousel__next--in-place` — Vertically centered inside the viewport, inset from edges.
- `.carousel__previous--modal` / `.carousel__next--modal` — Vertically centered, positioned outside the viewport bounds.
- `.carousel__previous--miniatures` / `.carousel__next--miniatures` — Relative positioning (inline with thumbnails).
### Dot Indicator Classes
- `.carousel__dots` — Flex container for pagination dots, centered with gap.
- `.carousel__dot` — Individual dot. `bg-default` by default, `bg-accent` when selected. Theme-aware border-radius.
### Thumbnail Classes
- `.carousel__thumbnails` — Flex container for thumbnail navigation. Centered with gap.
- `.carousel__thumbnails--miniatures` — Removes top margin for miniatures type.
- `.carousel__thumbnail` — Individual thumbnail button. `size-16`, `rounded-2xl`. Selected state uses `box-shadow` ring with accent color (no layout shift).
### Interactive States
- **Hover**: `[data-hovered="true"]` on `.carousel__previous` / `.carousel__next` — applies `bg-default-hover`.
- **Pressed**: `[data-pressed="true"]` on `.carousel__previous` / `.carousel__next` — applies `bg-default-hover`.
- **Disabled**: `[aria-disabled="true"]` on `.carousel__previous` / `.carousel__next` — applies disabled opacity.
- **Focus visible**: `[data-focus-visible="true"]` on buttons, dots, and thumbnails — applies focus ring.
- **Dot selected**: `[data-selected="true"]` on `.carousel__dot` — applies `bg-accent`.
- **Thumbnail selected**: `[data-selected="true"]` on `.carousel__thumbnail` — applies accent `box-shadow` ring.
- **Thumbnail hover**: `[data-hovered="true"]` on `.carousel__thumbnail` — applies `opacity: 0.85`.
- **Thumbnail pressed**: `[data-pressed="true"]` on `.carousel__thumbnail` — applies `scale(0.95)`.
- **Reduced motion**: `prefers-reduced-motion: reduce` disables all thumbnail transitions.
### CSS Variables
- `--carousel-gap` — Spacing between slides (default: `calc(var(--spacing) * 4)`).
## API Reference
### Carousel
The root container. Sets up Embla Carousel and provides context to all subcomponents.
| Prop | Type | Default | Description |
| --------- | --------------------------------------- | ------------ | -------------------------------------------------------------------------------------- |
| `opts` | `EmblaOptionsType` | — | Embla Carousel options. See [Embla docs](https://www.embla-carousel.com/api/options/). |
| `plugins` | `EmblaPluginType[]` | — | Embla Carousel plugins. See [Embla plugins](https://www.embla-carousel.com/plugins/). |
| `type` | `"in-place" \| "modal" \| "miniatures"` | `"in-place"` | Layout type controlling navigation button positioning. |
| `setApi` | `(api: EmblaCarouselType) => void` | — | Callback to receive the Embla API instance for programmatic control. |
Also supports all HTML `div` props.
### Carousel.Content
The scrollable slide container. Renders the Embla viewport wrapper and flex content area.
Also supports all HTML `div` props.
### Carousel.Item
An individual slide. Set `className="basis-1/3"` (or similar) to show multiple slides per viewport.
Also supports all HTML `div` props.
### Carousel.Previous
Navigation button to scroll to the previous slide. Automatically disabled when at the start (unless looping).
| Prop | Type | Default | Description |
| ------ | ----------- | ------- | ------------------------------------------- |
| `icon` | `ReactNode` | — | Custom icon to replace the default chevron. |
Also supports all HTML `button` props.
### Carousel.Next
Navigation button to scroll to the next slide. Automatically disabled when at the end (unless looping).
| Prop | Type | Default | Description |
| ------ | ----------- | ------- | ------------------------------------------- |
| `icon` | `ReactNode` | — | Custom icon to replace the default chevron. |
Also supports all HTML `button` props.
### Carousel.Dots
Pagination dot indicators. Renders one dot per scroll snap. Automatically hidden when there is only one snap point.
| Prop | Type | Default | Description |
| ----------- | -------------------------------------------------------------- | ------- | ------------------------------------ |
| `renderDot` | `(props: { index: number; isSelected: boolean }) => ReactNode` | — | Custom render function for each dot. |
Also supports all HTML `div` props.
### Carousel.Thumbnails
Container for thumbnail navigation buttons. Renders as a `tablist`.
Also supports all HTML `div` props.
### Carousel.Thumbnail
An individual thumbnail button linked to a slide index. Clicking navigates the carousel to that slide.
| Prop | Type | Default | Description |
| ------- | -------- | ------- | -------------------------------------------------------------------- |
| `index` | `number` | — | The slide index this thumbnail navigates to (0-based). Required. |
| `src` | `string` | — | Image source URL. Alternatively, pass `children` for custom content. |
| `alt` | `string` | `""` | Alt text for the thumbnail image. |
Also supports all HTML `button` props.
### useCarousel
A hook to access the carousel context from any descendant component.
```tsx
const {
api,
selectedIndex,
scrollSnapCount,
canScrollPrev,
canScrollNext,
scrollPrev,
scrollNext,
scrollTo,
} = useCarousel();
```
**Returns:**
| Property | Type | Description |
| ----------------- | -------------------------------- | --------------------------------------- |
| `api` | `EmblaCarouselType \| undefined` | The Embla API instance. |
| `selectedIndex` | `number` | Currently active slide index. |
| `scrollSnapCount` | `number` | Total number of scroll snap points. |
| `canScrollPrev` | `boolean` | Whether scrolling backward is possible. |
| `canScrollNext` | `boolean` | Whether scrolling forward is possible. |
| `scrollPrev` | `() => void` | Scroll to the previous slide. |
| `scrollNext` | `() => void` | Scroll to the next slide. |
| `scrollTo` | `(index: number) => void` | Scroll to a specific slide by index. |
# Cell Color Picker
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/cell-color-picker
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/cell-color-picker.mdx
> A compact color picker styled as a settings cell with preset palettes and custom color input.
## Usage
{/* DEMO cell-color-picker-default */}
```tsx
"use client";
import { CellColorPicker } from "@thenamespace/uikit";
import { ColorArea } from "@thenamespace/uikit/color-area";
import { ColorSlider } from "@thenamespace/uikit/color-slider";
import { Label } from "@thenamespace/uikit/label";
function PickerControls() {
return (
<>
);
}
function Picker({
label = "Accent",
variant = "default",
}: {
label?: string;
variant?: "default" | "secondary";
}) {
return (
{label}
);
}
export const DemoDefaultExample = () => (
;
```
## Controlled
{/* DEMO cell-color-picker-controlled */}
```tsx
"use client";
import { useState } from "react";
import { CellColorPicker } from "@thenamespace/uikit";
import { ColorArea } from "@thenamespace/uikit/color-area";
import { ColorSlider } from "@thenamespace/uikit/color-slider";
import { Label } from "@thenamespace/uikit/label";
import { parseColor } from "react-aria-components";
function PickerControls() {
return (
<>
);
}
export const DemoControlledExample = function Demo() {
const [color, setColor] = useState(parseColor("#3B82F6"));
return (
Accent
);
};
```
## Disabled
{/* DEMO cell-color-picker-disabled */}
```tsx
"use client";
import { CellColorPicker } from "@thenamespace/uikit";
import { ColorArea } from "@thenamespace/uikit/color-area";
import { Label } from "@thenamespace/uikit/label";
export const DemoDisabledExample = () => (
Accent
);
```
## Settings Group
{/* DEMO cell-color-picker-settings-group */}
```tsx
"use client";
import { useState } from "react";
import { CellColorPicker } from "@thenamespace/uikit";
import { ColorArea } from "@thenamespace/uikit/color-area";
import { ColorSlider } from "@thenamespace/uikit/color-slider";
import { Label } from "@thenamespace/uikit/label";
import { parseColor } from "react-aria-components";
function PickerControls() {
return (
<>
);
}
export const DemoSettingsGroupExample = function Demo() {
const [accent, setAccent] = useState(parseColor("#3B82F6"));
const [success, setSuccess] = useState(parseColor("#22C55E"));
const [danger, setDanger] = useState(parseColor("#EF4444"));
return (
);
}
function Picker({
label = "Accent",
variant = "default",
}: {
label?: string;
variant?: "default" | "secondary";
}) {
return (
{label}
);
}
export const DemoVariantsExample = () => (
);
}
const presets = [
"#ef4444",
"#f97316",
"#eab308",
"#22c55e",
"#06b6d4",
"#3b82f6",
"#8b5cf6",
"#ec4899",
"#f43f5e",
];
export const DemoWithPresetsExample = function Demo() {
const [color, setColor] = useState(parseColor("#3B82F6"));
return (
Brand Color
{presets.map((preset) => (
))}
#
);
};
```
## CSS Classes
### Base Classes
- `.cell-color-picker` - Root wrapper
### Element Classes
- `.cell-color-picker__trigger` - The visible cell row button
- `.cell-color-picker__trigger--default` - Default variant trigger styling
- `.cell-color-picker__trigger--secondary` - Secondary variant trigger styling
- `.cell-color-picker__label` - Leading text label
- `.cell-color-picker__value-display` - Hex value text display
- `.cell-color-picker__swatch` - Color swatch preview
- `.cell-color-picker__popover` - Dropdown color picker panel
## API Reference
### CellColorPicker
The root component. Wraps Namespace UIKit [ColorPicker](https://namespace.com/docs/react/components/color-picker) with cell-style layout.
| Prop | Type | Default | Description |
| --------- | -------------------------- | ----------- | -------------------- |
| `variant` | `'default' \| 'secondary'` | `'default'` | Visual style variant |
Also supports all RAC [ColorPicker](https://react-spectrum.adobe.com/react-aria/ColorPicker.html) props except `children` (`defaultValue`, `value`, `onChange`, etc.).
### CellColorPicker.Trigger
The visible cell row button. Wraps RAC [Button](https://react-spectrum.adobe.com/react-aria/Button.html).
Also supports all RAC [Button](https://react-spectrum.adobe.com/react-aria/Button.html) props.
### CellColorPicker.Label
Leading text label rendered as a `span`.
| Prop | Type | Default | Description |
| ---------- | ----------- | ------- | ----------- |
| `children` | `ReactNode` | - | Label text |
Also supports all native `span` HTML attributes.
### CellColorPicker.ValueDisplay
Displays the current color as a hex value (e.g. `#FF5733`). Automatically reads from the color picker state.
Also supports all native `span` HTML attributes.
### CellColorPicker.Swatch
Color swatch preview. Wraps Namespace UIKit [ColorSwatch](https://namespace.com/docs/react/components/color-picker).
Also supports all Namespace UIKit ColorSwatch props.
### CellColorPicker.Popover
Dropdown color picker panel. Wraps Namespace UIKit `ColorPicker.Popover`.
| Prop | Type | Default | Description |
| ----------- | ----------- | -------------- | ----------------------------------------- |
| `placement` | `Placement` | `'bottom end'` | Popover placement relative to the trigger |
Also supports all Namespace UIKit ColorPicker.Popover props.
# Cell Select
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/cell-select
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/cell-select.mdx
> A compact select input styled as a settings cell, ideal for preference panels and configuration forms.
## Usage
{/* DEMO cell-select-default */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import { useState } from "react";
import { CellSelect } from "@thenamespace/uikit";
import { ListBox } from "@thenamespace/uikit/list-box";
const themes = [
{ id: "default", name: "Default" },
{ id: "dark", name: "Dark" },
{ id: "system", name: "System" },
];
function ThemeItems() {
return themes.map((item) => (
{item.name}
));
}
function ThemeSelect({
variant = "default",
}: {
variant?: "default" | "secondary";
}) {
const [value, setValue] = useState("default");
return (
Theme
);
}
export const DemoDefaultExample = () => (
;
```
## Controlled
{/* DEMO cell-select-controlled */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import { useState } from "react";
import { CellSelect } from "@thenamespace/uikit";
import { ListBox } from "@thenamespace/uikit/list-box";
const themes = [
{ id: "default", name: "Default" },
{ id: "dark", name: "Dark" },
{ id: "system", name: "System" },
];
function ThemeItems() {
return themes.map((item) => (
{item.name}
));
}
export const DemoControlledExample = function Demo() {
const [value, setValue] = useState("default");
const selected = themes.find((item) => item.id === value);
return (
Theme
);
};
```
## Custom Value
{/* DEMO cell-select-custom-value */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import { useState } from "react";
import {
Globe02Icon,
PaintBoardIcon,
SmileIcon,
} from "@thenamespace/uikit/icons";
import { HugeiconsIcon, type IconSvgElement } from "@thenamespace/uikit/icons";
import { CellSelect } from "@thenamespace/uikit";
import { ListBox } from "@thenamespace/uikit/list-box";
const iconSets = [
{ icon: SmileIcon, id: "gravity", name: "Gravity" },
{ icon: PaintBoardIcon, id: "heroicons", name: "Heroicons" },
{ icon: Globe02Icon, id: "lucide", name: "Lucide" },
];
function IconSetGlyph({ icon }: { icon: IconSvgElement }) {
return
Icons
{({ defaultChildren, isPlaceholder, state }) => {
if (isPlaceholder || state.selectedItems.length === 0)
return defaultChildren;
const item = iconSets.find(
(option) => option.id === state.selectedItems[0]?.key,
);
return item ? (
{item.name}
{iconSets.map((item) => (
))}
);
};
```
## Disabled
{/* DEMO cell-select-disabled */}
```tsx
"use client";
import { CellSelect } from "@thenamespace/uikit";
import { ListBox } from "@thenamespace/uikit/list-box";
const themes = [
{ id: "default", name: "Default" },
{ id: "dark", name: "Dark" },
{ id: "system", name: "System" },
];
function ThemeItems() {
return themes.map((item) => (
{item.name}
));
}
export const DemoDisabledExample = () => (
Theme
);
```
## Font Family
{/* DEMO cell-select-font-family */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import { useState } from "react";
import { CellSelect } from "@thenamespace/uikit";
import { ListBox } from "@thenamespace/uikit/list-box";
const fonts = [
{ id: "inter", name: "Inter" },
{ id: "roboto", name: "Roboto" },
{ id: "system", name: "System" },
{ id: "georgia", name: "Georgia" },
];
function FontSelect({
label,
variant = "default",
}: {
label: string;
variant?: "default" | "secondary";
}) {
const [value, setValue] = useState("inter");
return (
{label}
{({ defaultChildren, isPlaceholder, state }) => {
if (isPlaceholder || state.selectedItems.length === 0)
return defaultChildren;
const item = fonts.find(
(option) => option.id === state.selectedItems[0]?.key,
);
return item ? (
{item.name}
Ag
) : (
defaultChildren
);
}}
{fonts.map((item) => (
{item.name}
))}
);
}
export const DemoFontFamilyExample = () => (
{setting.label}
{setting.options.map((item) => (
{item.name}
))}
);
}
export const DemoSettingsGroupExample = () => (
{item.name}
));
}
function ThemeSelect({
variant = "default",
}: {
variant?: "default" | "secondary";
}) {
const [value, setValue] = useState("default");
return (
Theme
);
}
export const DemoVariantsExample = () => (
# Cell Slider
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/cell-slider
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/cell-slider.mdx
> A range slider styled as a settings cell with label, value display, and step configuration.
## Usage
{/* DEMO cell-slider-default */}
```tsx
"use client";
import { CellSlider } from "@thenamespace/uikit";
const decimalProps = {
formatOptions: { maximumFractionDigits: 2, minimumFractionDigits: 2 },
maxValue: 1,
minValue: 0,
step: 0.01,
} as const;
function SliderContents({ label }: { label: string }) {
return (
{label}
);
}
export const DemoDefaultExample = () => (
);
```
## Anatomy
Import the CellSlider component and access all parts using dot notation.
```tsx
import { CellSlider } from "@thenamespace/uikit";
;
```
## Controlled
{/* DEMO cell-slider-controlled */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import { useState } from "react";
import { CellSlider } from "@thenamespace/uikit";
const decimalProps = {
formatOptions: { maximumFractionDigits: 2, minimumFractionDigits: 2 },
maxValue: 1,
minValue: 0,
step: 0.01,
} as const;
function SliderContents({ label }: { label: string }) {
return (
{label}
);
}
export const DemoControlledExample = function Demo() {
const [value, setValue] = useState(0.5);
return (
);
};
```
## Disabled
{/* DEMO cell-slider-disabled */}
```tsx
"use client";
import { CellSlider } from "@thenamespace/uikit";
const decimalProps = {
formatOptions: { maximumFractionDigits: 2, minimumFractionDigits: 2 },
maxValue: 1,
minValue: 0,
step: 0.01,
} as const;
function SliderContents({ label }: { label: string }) {
return (
{label}
);
}
export const DemoDisabledExample = () => (
);
```
## Integer Step
{/* DEMO cell-slider-integer-step */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import { useState } from "react";
import { CellSlider } from "@thenamespace/uikit";
function SliderContents({ label }: { label: string }) {
return (
{label}
);
}
export const DemoIntegerStepExample = function Demo() {
const [value, setValue] = useState(75);
return (
);
};
```
## Secondary Group
{/* DEMO cell-slider-secondary-group */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import { useState } from "react";
import { CellSlider } from "@thenamespace/uikit";
const decimalProps = {
formatOptions: { maximumFractionDigits: 2, minimumFractionDigits: 2 },
maxValue: 1,
minValue: 0,
step: 0.01,
} as const;
function SliderContents({ label }: { label: string }) {
return (
{label}
);
}
function ControlledCellSlider({
defaultValue,
label,
variant = "default",
}: {
defaultValue: number;
label: string;
variant?: "default" | "secondary";
}) {
const [value, setValue] = useState(defaultValue);
return (
);
}
export const DemoSecondaryGroupExample = () => (
{label}
);
}
function ControlledCellSlider({
defaultValue,
label,
variant = "default",
}: {
defaultValue: number;
label: string;
variant?: "default" | "secondary";
}) {
const [value, setValue] = useState(defaultValue);
return (
);
}
export const DemoSettingsGroupExample = () => (
);
```
## Variants
{/* DEMO cell-slider-variants */}
```tsx
"use client";
import { CellSlider } from "@thenamespace/uikit";
const decimalProps = {
formatOptions: { maximumFractionDigits: 2, minimumFractionDigits: 2 },
maxValue: 1,
minValue: 0,
step: 0.01,
} as const;
function SliderContents({ label }: { label: string }) {
return (
{label}
);
}
export const DemoVariantsExample = () => (
# Cell Switch
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/cell-switch
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/cell-switch.mdx
> A toggle switch styled as a settings cell with label and description, ideal for preference panels.
## Usage
{/* DEMO cell-switch-default */}
```tsx
"use client";
import { CellSwitch } from "@thenamespace/uikit";
function SwitchContents({ label }: { label: string }) {
return (
{label}
);
}
export const DemoDefaultExample = () => (
);
```
## Anatomy
Import the CellSwitch component and access all parts using dot notation.
```tsx
import { CellSwitch } from "@thenamespace/uikit";
;
```
## Controlled
{/* DEMO cell-switch-controlled */}
```tsx
"use client";
import { useState } from "react";
import { CellSwitch } from "@thenamespace/uikit";
function SwitchContents({ label }: { label: string }) {
return (
{label}
);
}
export const DemoControlledExample = function Demo() {
const [selected, setSelected] = useState(true);
return (
);
};
```
## Disabled
{/* DEMO cell-switch-disabled */}
```tsx
"use client";
import { CellSwitch } from "@thenamespace/uikit";
function SwitchContents({ label }: { label: string }) {
return (
{label}
);
}
export const DemoDisabledExample = () => (
);
```
## Feature Announcement
{/* DEMO cell-switch-feature-announcement */}
```tsx
"use client";
import { useState } from "react";
import { CellSwitch } from "@thenamespace/uikit";
import { Chip } from "@thenamespace/uikit/chip";
export const DemoFeatureAnnouncementExample = function Demo() {
const [selected, setSelected] = useState(false);
return (
);
};
```
## Secondary Group
{/* DEMO cell-switch-secondary-group */}
```tsx
"use client";
import { useState } from "react";
import { CellSwitch } from "@thenamespace/uikit";
function SwitchContents({ label }: { label: string }) {
return (
{label}
);
}
function ControlledSwitch({
defaultSelected,
label,
variant = "default",
}: {
defaultSelected: boolean;
label: string;
variant?: "default" | "secondary";
}) {
const [selected, setSelected] = useState(defaultSelected);
return (
);
}
export const DemoSecondaryGroupExample = () => (
{label}
);
}
function ControlledSwitch({
defaultSelected,
label,
variant = "default",
}: {
defaultSelected: boolean;
label: string;
variant?: "default" | "secondary";
}) {
const [selected, setSelected] = useState(defaultSelected);
return (
);
}
export const DemoSettingsGroupExample = () => (
{label}
);
}
export const DemoVariantsExample = () => (
# Chain Of Thought
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/chain-of-thought
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/chain-of-thought.mdx
> A collapsible reasoning timeline for assistant thinking, progress, and agent traces.
## Usage
{/* DEMO chain-of-thought-default */}
```tsx
"use client";
import { ChainOfThought } from "@thenamespace/uikit";
export const DemoDefaultExample = () => (
Thought for 4 seconds
Looked up Namespace UIKit chat template patterns for message layout
and composer spacing.
Mapped the template structure to SDK-agnostic compound components.
);
```
Use `ChainOfThought` to show assistant reasoning, progress, tool discovery, or agent traces without coupling to an AI SDK.
## Streaming
{/* DEMO chain-of-thought-streaming */}
```tsx
"use client";
import { ChainOfThought } from "@thenamespace/uikit";
export const DemoStreamingExample = () => (
Thinking...
Breaking the request into presentation-only UIKit components.
);
```
Set `isStreaming` to shimmer the trigger while reasoning is still in progress.
## Agent Trace
{/* DEMO chain-of-thought-agent-trace */}
```tsx
"use client";
import { useState, type ReactNode } from "react";
import { ChainOfThought } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
function CollapsibleStep({
children,
defaultOpen = true,
icon,
title,
}: {
children: ReactNode;
defaultOpen?: boolean;
icon?: ReactNode;
title: string;
}) {
const [open, setOpen] = useState(defaultOpen);
return (
setOpen((value) => !value)}
>
);
}
function TraceSection({
children,
defaultExpanded = true,
isStreaming = false,
title,
}: {
children: ReactNode;
defaultExpanded?: boolean;
isStreaming?: boolean;
title: string;
}) {
return (
{title}
{children}
);
}
function ReadFile({ children }: { children: ReactNode }) {
return (
Read app/layout.tsx
Read app/globals.css
{[
["button", "Read components/ui/button.tsx"],
["input", "Read components/ui/input.tsx"],
["card", "Read components/ui/card.tsx"],
["label", "Read components/ui/label.tsx"],
].map(([name, file]) => (
{file}
))}
Updated components/login-form.tsx
Updated app/layout.tsx
);
}
export const DemoAgentTraceExample = () => setOpen((value) => !value)}
>
);
}
function TraceSection({
children,
defaultExpanded = true,
isStreaming = false,
title,
}: {
children: ReactNode;
defaultExpanded?: boolean;
isStreaming?: boolean;
title: string;
}) {
return (
{title}
{children}
);
}
function ReadFile({ children }: { children: ReactNode }) {
return (
Read app/layout.tsx
Read app/globals.css
{[
["button", "Read components/ui/button.tsx"],
["input", "Read components/ui/input.tsx"],
["card", "Read components/ui/card.tsx"],
["label", "Read components/ui/label.tsx"],
].map(([name, file]) => (
{file}
))}
Updated components/login-form.tsx
Updated app/layout.tsx
);
}
export const DemoAgentTraceStreamingExample = () => (
Thought for 2s
Read layout and globals.
;
```
## CSS Classes
- `.chain-of-thought` - Root disclosure wrapper
- `.chain-of-thought__trigger` - Collapsible trigger
- `.chain-of-thought__content` - Disclosure content panel
- `.chain-of-thought__steps` - Vertical step timeline
- `.chain-of-thought__step` - One step in the timeline
- `.chain-of-thought__step-label` - Optional step label
- `.chain-of-thought__step-content` - Step body content
## API Reference
### ChainOfThought
Extends Namespace UIKit `Disclosure` props.
| Prop | Type | Default | Description |
| ----------------- | ----------- | ------- | ------------------------------------------------ |
| `children` | `ReactNode` | - | Trigger and content |
| `isStreaming` | `boolean` | `false` | Applies streaming shimmer styling to the trigger |
| `defaultExpanded` | `boolean` | - | Open by default for uncontrolled usage |
| `isExpanded` | `boolean` | - | Controlled expanded state |
### ChainOfThought.Trigger
Extends Namespace UIKit `Button` props. Renders the disclosure trigger.
### ChainOfThought.Content
Extends `Disclosure.Content` props. Wraps the expanded content body.
### ChainOfThought.Steps
Renders the vertical timeline container. Also supports native `div` props.
### ChainOfThought.Step
Renders one timeline step. Also supports native `div` props.
| Prop | Type | Default | Description |
| ---------- | ----------- | ------- | ---------------------------------------------- |
| `label` | `ReactNode` | - | Optional label rendered above the step content |
| `children` | `ReactNode` | - | Step body content |
# Chart Tooltip
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/chart-tooltip
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/chart-tooltip.mdx
> A composable tooltip for chart data points with customizable indicators, labels, and value formatters.
## Usage
{/* DEMO chart-tooltip-default */}
```tsx
"use client";
import { ChartTooltip } from "@thenamespace/uikit";
export const DemoDefaultExample = () => (
January
Revenue
$12,400
Expenses
$8,200
);
```
## Anatomy
Import the ChartTooltip component and access all parts using dot notation.
```tsx
import { ChartTooltip } from "@thenamespace/uikit";
;
```
## Auto Content
{/* DEMO chart-tooltip-auto-content */}
```tsx
"use client";
import { ChartTooltip } from "@thenamespace/uikit";
export const DemoAutoContentExample = () => (
{indicator === "line" ? "Line Indicators" : "All Chart Colors"}
{chartColors.map(([token, label]) => (
{token}
{label}
))}
);
}
export const DemoChartColorsExample = () => (
new Date(String(label)).toLocaleDateString("en-US", {
day: "numeric",
month: "long",
year: "numeric",
})
}
payload={[
{ name: "Portfolio", stroke: "var(--chart-3)", value: 24801.32 },
{ name: "Benchmark", stroke: "var(--chart-2)", value: 21500 },
]}
valueFormatter={(value) => `$${Number(value).toLocaleString()}`}
/>
);
```
## Inactive
{/* DEMO chart-tooltip-inactive */}
```tsx
"use client";
import { ChartTooltip } from "@thenamespace/uikit";
export const DemoInactiveExample = () => (
March 2025
{[
["Organic", "15,200", "var(--chart-3)"],
["Paid Ads", "8,400", "var(--chart-2)"],
["Referral", "3,100", "var(--chart-1)"],
].map(([label, value, color]) => (
{label}
{value}
))}
);
```
## No Header
{/* DEMO chart-tooltip-no-header */}
```tsx
"use client";
import { ChartTooltip } from "@thenamespace/uikit";
export const DemoNoHeaderExample = () => (
Sales
458
);
```
## CSS Classes
### Element Classes
- `.chart-tooltip` — Root tooltip card container. Rounded border with surface background and overlay shadow.
- `.chart-tooltip__header` — Optional title row (e.g., the X-axis label). Muted 12px medium text.
- `.chart-tooltip__item` — A single series entry row. Flex layout with gap.
- `.chart-tooltip__indicator` — Color marker next to the series name.
- `.chart-tooltip__indicator--dot` — Dot-shaped indicator. Small circle (8px).
- `.chart-tooltip__indicator--line` — Line-shaped indicator. Tall narrow pill (12px × 4px).
- `.chart-tooltip__label` — Series name text. Muted 12px, fills available space.
- `.chart-tooltip__value` — Series data value. Semibold 12px foreground text.
## API Reference
### ChartTooltip
The root tooltip container. Controls visibility and indicator style via context.
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `active` | `boolean` | `true` | Controls visibility. When `false`, the tooltip is not rendered. |
| `indicator` | `"dot" \| "line"` | `"dot"` | Shape of the color indicator next to each series name. |
| `children` | `ReactNode` | — | Tooltip content — typically `Header`, `Item`, `Indicator`, `Label`, and `Value` sub-components. |
Also supports all native `div` HTML attributes.
### ChartTooltip.Content
Auto-renders a tooltip from Recharts payload data. Pass as the `content` prop of a Recharts ``:
```tsx
# Chat Attachment
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/chat-attachment
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/chat-attachment.mdx
> Attachment previews and composer file input helpers for AI chat surfaces.
## Usage
{/* DEMO chat-attachment-default */}
```tsx
"use client";
import {
ChatAttachment,
ChatAttachmentGroup,
ChatMessage,
} from "@thenamespace/uikit";
const image = "/assets/images/egg.webp";
export const DemoDefaultExample = () => (
What is in this screenshot?
);
```
Use `ChatAttachment` for compact file previews in messages or prompt composers.
## Composer
{/* DEMO chat-attachment-composer */}
```tsx
"use client";
import { useEffect, useRef, useState } from "react";
import {
ChatAttachment,
ChatAttachmentGroup,
ChatAttachmentInput,
PromptInput,
} from "@thenamespace/uikit";
import { ArrowUp01Icon, Attachment01Icon } from "@thenamespace/uikit/icons";
import { HugeiconsIcon } from "@thenamespace/uikit/icons";
interface Attachment {
id: string;
mimeType: string;
name: string;
src?: string;
}
function ComposerDemo() {
const [attachments, setAttachments] = useState([]);
const refs = useRef([]);
useEffect(() => {
refs.current = attachments;
}, [attachments]);
useEffect(
() => () =>
refs.current.forEach((item) => {
if (item.src?.startsWith("blob:")) URL.revokeObjectURL(item.src);
}),
[],
);
const add = (files: File[]) =>
setAttachments((values) => [
...values,
...files.map((file) => ({
id: `${file.name}-${file.lastModified}-${crypto.randomUUID()}`,
mimeType: file.type,
name: file.name,
src: file.type.startsWith("image/") ? URL.createObjectURL(file) : undefined,
})),
]);
return (
(
{attachments.length ? (
{attachments.map((item) => (
setAttachments((values) =>
values.filter((value) => value.id !== item.id),
)
}
/>
))}
) : null}
(
)}
/>
)}
/>
);
}
export const DemoComposerExample = () =>
);
```
Use `ChatAttachmentGroup` to arrange multiple attachments.
## Anatomy
```tsx
import {ChatAttachment, ChatAttachmentGroup, ChatAttachmentInput, PromptInput} from "@thenamespace/uikit";
{/* composer content */} }
/>
```
## CSS Classes
- `.chat-attachment` - Attachment preview tile
- `.chat-attachment__preview` - Preview media wrapper
- `.chat-attachment__preview-image` - Image preview
- `.chat-attachment__preview-video` - Video preview
- `.chat-attachment__preview-fallback` - Fallback document icon
- `.chat-attachment__remove` - Remove button
- `.chat-attachment-group` - Attachment group wrapper
## API Reference
### ChatAttachment
| Prop | Type | Default | Description |
| ----------- | ---------------------------------------------------------- | --------------- | ------------------------------------------ |
| `mediaType` | `'audio' \| 'document' \| 'image' \| 'unknown' \| 'video'` | inferred | Attachment media type |
| `mimeType` | `string` | - | MIME type used to infer media type |
| `name` | `string` | - | Attachment file name |
| `src` | `string` | - | Preview URL for image or video attachments |
| `children` | `ReactNode` | default preview | Custom attachment content |
### ChatAttachment.Preview
Renders image, video, or document fallback preview. Accepts `children` to replace the preview content.
### ChatAttachment.Remove
Extends Namespace UIKit `CloseButton` props. Use it to remove an attachment from composer state.
### ChatAttachmentInput
Provides file-picker and drag-and-drop behavior.
| Prop | Type | Default | Description |
| ----------------- | ------------------------- | ------- | ----------------------------------------- |
| `accept` | `string` | - | Native file input accept filter |
| `multiple` | `boolean` | `true` | Allow multiple files |
| `disabled` | `boolean` | `false` | Disable picker and drop behavior |
| `onFilesSelected` | `(files: File[]) => void` | - | Called when files are selected or dropped |
### ChatAttachmentInput.Trigger
Opens the hidden file input. Use `render` to wire it to another button.
### ChatAttachmentInput.Dropzone
Adds drag-and-drop file handling. Use `render` to attach drop behavior to `PromptInput.Shell`.
# Chat Conversation
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/chat-conversation
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/chat-conversation.mdx
> A stick-to-bottom conversation viewport for streaming chat messages.
## Usage
{/* DEMO chat-conversation-default */}
```tsx
"use client";
import {
ChainOfThought,
ChatConversation,
ChatMessage,
ChatMessageActions,
Markdown,
} from "@thenamespace/uikit";
interface Message {
id: string;
role: "assistant" | "user";
text: string;
trace?: boolean;
}
const messages: Message[] = [
{
id: "1",
role: "user",
text: "How does auto-scroll work in chat UIs?",
},
{
id: "2",
role: "assistant",
text: `Stick-to-bottom keeps the viewport pinned to the latest message while you stream.
It also leaves the user in control: once they scroll away from the bottom, new content can arrive without snapping the viewport away from what they are reading.`,
},
{
id: "3",
role: "user",
text: "What happens when the assistant is doing multiple steps?",
},
{
id: "4",
role: "assistant",
text: "You can combine the conversation viewport with reasoning and tool UI so the whole exchange remains in one scrollable surface.",
trace: true,
},
];
function MessageView({
message,
showActions = false,
}: {
message: Message;
showActions?: boolean;
}) {
return message.role === "user" ? (
{message.text}
) : (
{message.text}
{message.trace ? (
Thought for 2s
Verified the viewport remains pinned while the assistant
streams.
Added reasoning UI inline with the assistant message body.
) : null}
{showActions ? (
) : null}
);
}
function DefaultDemo() {
return (
{messages.map((message) => (
);
}
export const DemoDefaultExample = () =>
{message.text}
) : (
{message.text}
{message.trace ? (
Thought for 2s
Verified the viewport remains pinned while the assistant
streams.
Added reasoning UI inline with the assistant message body.
) : null}
{showActions ? (
) : null}
);
}
const initialFullChatMessages: Message[] = [
{
id: "1",
role: "user",
text: "Build a settings page with profile and notifications.",
},
{
id: "2",
role: "assistant",
text: `Here is a **settings layout** outline with profile, notifications, and a danger zone section.
- Profile card for avatar, display name, and email
- Notification preferences grouped by channel
- Danger zone with clear destructive affordances`,
trace: true,
},
{
id: "3",
role: "user",
text: "Add a compact version that works well in a dashboard drawer.",
},
{
id: "4",
role: "assistant",
text: "For a drawer, I would reduce section padding, keep labels visible, and move destructive actions behind a confirmation step. The same components can stay responsive with container width constraints.",
},
];
function FullChatDemo() {
const [currentMessages, setMessages] = useState(initialFullChatMessages);
const [value, setValue] = useState("");
const [status, setStatus] = useState<"ready" | "streaming" | "submitted">(
"ready",
);
const timers = useRef([]);
const clearTimers = useCallback(() => {
timers.current.forEach((timer) => window.clearTimeout(timer));
timers.current = [];
}, []);
useEffect(() => () => clearTimers(), [clearTimers]);
const stop = () => {
clearTimers();
setStatus("ready");
};
const submit = () => {
const text = value.trim();
if (!text || status !== "ready") return;
setMessages((current) => [
...current,
{ id: String(Date.now()), role: "user", text },
]);
setValue("");
setStatus("submitted");
clearTimers();
timers.current.push(
window.setTimeout(() => setStatus("streaming"), 300),
window.setTimeout(() => {
setMessages((current) => [
...current,
{
id: String(Date.now() + 1),
role: "assistant",
text: "This is a mocked assistant reply rendered with Namespace UIKit AI components.",
},
]);
setStatus("ready");
}, 1200),
);
};
return (
{currentMessages.map((message) => (
AI can make mistakes. Check important info.
);
}
export const DemoFullChatExample = () =>
{messages}
;
```
### With Scroll Button
{/* DEMO chat-conversation-with-scroll-button */}
```tsx
"use client";
import { useEffect, useRef } from "react";
import {
ChainOfThought,
ChatConversation,
ChatMessage,
ChatMessageActions,
Markdown,
} from "@thenamespace/uikit";
interface Message {
id: string;
role: "assistant" | "user";
text: string;
trace?: boolean;
}
function MessageView({
message,
showActions = false,
}: {
message: Message;
showActions?: boolean;
}) {
return message.role === "user" ? (
{message.text}
) : (
{message.text}
{message.trace ? (
Thought for 2s
Verified the viewport remains pinned while the assistant
streams.
Added reasoning UI inline with the assistant message body.
) : null}
{showActions ? (
) : null}
);
}
const scrollMessages: Message[] = [
{
id: "1",
role: "user",
text: "Can you summarize the release notes?",
},
{
id: "2",
role: "assistant",
text: `The release focuses on the chat surface, component polish, and small API cleanup.
- Chat messages now compose with markdown, sources, and actions
- Conversation viewports keep streaming content readable
- AI components share the same spacing and typography rhythm`,
},
{
id: "3",
role: "user",
text: "What changed for long conversations?",
},
{
id: "4",
role: "assistant",
text: "Long threads keep their message column centered while the viewport owns scrolling. The optional jump button can be added when an app wants an explicit return-to-bottom control.",
},
{
id: "5",
role: "user",
text: "Show me the button treatment.",
},
{
id: "6",
role: "assistant",
text: "Scroll away from the latest response and the button appears over the lower edge of the conversation. Pressing it returns the viewport to the newest message.",
},
{
id: "7",
role: "assistant",
text: "The default conversation examples omit this control so teams can choose whether the extra affordance belongs in their product.",
},
];
function WithScrollButtonDemo() {
const conversationRef = useRef(null);
useEffect(() => {
const frame = window.requestAnimationFrame(() => {
const conversation = conversationRef.current;
conversation?.scrollTo({
behavior: "auto",
top: Math.max(
0,
conversation.scrollHeight - conversation.clientHeight - 160,
),
});
});
return () => window.cancelAnimationFrame(frame);
}, []);
return (
{scrollMessages.map((message) => (
);
}
export const DemoWithScrollButtonExample = () =>
# Chat List View
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/chat-list-view
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/chat-list-view.mdx
> Thread list rows for chat sidebars and conversation pickers.
## Usage
{/* DEMO chat-list-view-default */}
```tsx
"use client";
import { Comment01Icon } from "@thenamespace/uikit/icons";
import { HugeiconsIcon } from "@thenamespace/uikit/icons";
import { ChatListView } from "@thenamespace/uikit";
const chats = [
{
id: "1",
preview: "Can you help me draft a launch checklist?",
title: "Product launch planning",
updatedAt: "2h ago",
},
{
id: "2",
preview: "Summarize the customer feedback from last week.",
title: "Customer feedback review",
updatedAt: "Yesterday",
},
{
id: "3",
preview: "Rewrite this paragraph to sound more concise.",
title: "Copy editing help",
updatedAt: "Mon",
},
];
function DefaultDemo() {
return (
{(chat) => (
{chat.title}
{chat.preview}
{chat.updatedAt}
)}
);
}
export const DemoDefaultExample = () =>
{(chat) => (
{chat.title}
{chat.preview}
{chat.updatedAt}
)}
);
}
export const DemoCompactExample = () =>
Project planning
Last assistant reply preview
;
```
## CSS Classes
- `.chat-list-view` - Root list
- `.chat-list-view__item` - Thread row
- `.chat-list-view__icon` - Leading icon/avatar
- `.chat-list-view__item-content` - Row text content
- `.chat-list-view__title` - Thread title
- `.chat-list-view__preview` - Thread preview
- `.chat-list-view__meta` - Optional metadata
## API Reference
### ChatListView
Root list container. Supports native `div` props.
### ChatListView\.Item
Thread row. Supports native button/link composition depending on usage.
### ChatListView\.Icon
Leading icon slot.
### ChatListView\.ItemContent
Text content wrapper.
### ChatListView\.Title
Thread title slot.
### ChatListView\.Preview
Thread description or last-message preview slot.
### ChatListView\.Meta
Optional metadata slot, such as date or unread counts.
# Chat Loader
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/chat-loader
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/chat-loader.mdx
> Loading skeletons and typing placeholders for assistant responses.
## Usage
{/* DEMO chat-loader-default */}
```tsx
"use client";
import { ChatLoader } from "@thenamespace/uikit";
export const DemoDefaultExample = () => (
# Chat Message Actions
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/chat-message-actions
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/chat-message-actions.mdx
> Inline action buttons for assistant and user messages.
## Usage
{/* DEMO chat-message-actions-default */}
```tsx
"use client";
import { ChatMessage, ChatMessageActions } from "@thenamespace/uikit";
const Assistant = ({ children }: { children: React.ReactNode }) => (
{children}
);
export const DemoDefaultExample = () => (
Assistant responses can expose quick actions beneath the message body.
);
```
Use `ChatMessageActions` for copy, retry, rating, share, or custom message actions.
## Minimal
{/* DEMO chat-message-actions-minimal */}
```tsx
"use client";
import { ChatMessage, ChatMessageActions } from "@thenamespace/uikit";
const Assistant = ({ children }: { children: React.ReactNode }) => (
{children}
);
export const DemoMinimalExample = () => (
Minimal action set for compact layouts.
);
```
Use a smaller action set when only one or two actions are needed.
## Custom Icons
{/* DEMO chat-message-actions-custom-icons */}
```tsx
"use client";
import { ChatMessage, ChatMessageActions } from "@thenamespace/uikit";
import { Copy01Icon, HugeiconsIcon, ThumbsUpIcon } from "@thenamespace/uikit/icons";
const Assistant = ({ children }: { children: React.ReactNode }) => (
{children}
);
export const DemoCustomIconsExample = () => (
Swap preset icons via the Icon subcomponents.
);
```
Actions are composable, so you can bring your own icon set.
## Anatomy
```tsx
import { ChatMessageActions } from "@thenamespace/uikit";
...
...
;
```
## CSS Classes
- `.chat-message-actions` - Root action row
- `.chat-message-actions__action` - Individual icon button
## API Reference
### ChatMessageActions
Root action group. Supports native `div` props.
### ChatMessageActions.Action
Individual action button. Extends Namespace UIKit `Button` props.
# Chat Message
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/chat-message
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/chat-message.mdx
> Composable user and assistant message layouts for AI chat.
## Usage
{/* DEMO chat-message-default */}
```tsx
"use client";
import { ChatMessage } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
const Wrapper = ({ children }: { children: React.ReactNode }) => (
Can you explain how compound components help AI chat UIs stay
SDK-agnostic?
Compound components let you compose message layout explicitly while
keeping state in your app layer.
);
```
Use `ChatMessage` to compose assistant and user turns with avatars, bubbles, media, markdown, actions, and attachments.
## With Markdown
{/* DEMO chat-message-with-markdown */}
```tsx
"use client";
import { ChatMessage, Markdown } from "@thenamespace/uikit";
const Wrapper = ({ children }: { children: React.ReactNode }) => (
Show me markdown inside assistant messages.
{markdown}
);
```
Render assistant responses with rich markdown content.
## Loading
{/* DEMO chat-message-loading */}
```tsx
"use client";
import { ChatLoader, ChatMessage, TextShimmer } from "@thenamespace/uikit";
const Wrapper = ({ children }: { children: React.ReactNode }) => (
What is the weather in San Francisco?
Thinking...
);
```
Use the loading demo for pending assistant turns.
## Anatomy
```tsx
import {ChatMessage, Markdown} from "@thenamespace/uikit";
{response}
Hello
```
## CSS Classes
- `.chat-message--assistant` - Assistant message row
- `.chat-message--user` - User message wrapper
- `.chat-message__avatar` - Avatar slot
- `.chat-message__body` - Assistant body column
- `.chat-message__bubble` - User bubble
- `.chat-message__content` - Message content
- `.chat-message__actions` - Action row
## API Reference
### ChatMessage.Assistant
Assistant message root. Supports native `div` props.
### ChatMessage.User
User message root. Supports native `div` props.
### ChatMessage.Avatar
Avatar slot for assistant messages. Extends Namespace UIKit `Avatar` props.
### ChatMessage.Body
Assistant content column.
### ChatMessage.Bubble
User message bubble.
### ChatMessage.Content
Message text/content slot.
### ChatMessage.Actions
Container for message actions.
# Chat Source
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/chat-source
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/chat-source.mdx
> Citation chips and grouped source lists for AI responses.
## Usage
{/* DEMO chat-source-default */}
```tsx
"use client";
import { ChatMessage, ChatSource } from "@thenamespace/uikit";
const favicon = (url: string) =>
`/assets/favicons/${new URL(url).hostname.replaceAll(".", "-")}.png`;
const Assistant = ({ children }: { children: React.ReactNode }) => (
{children}
);
export const DemoDefaultExample = () => (
Here is an answer backed by a single web source.
);
```
Use `ChatSource` to cite a URL or uploaded document inline with an assistant answer.
## Document
{/* DEMO chat-source-document */}
```tsx
"use client";
import { ChatMessage, ChatSource } from "@thenamespace/uikit";
const Assistant = ({ children }: { children: React.ReactNode }) => (
{children}
);
export const DemoDocumentExample = () => (
Referenced an uploaded document.
);
```
Set `sourceType="document"` for uploaded or local files.
## Grouped
{/* DEMO chat-source-grouped */}
```tsx
"use client";
import { ChatMessage, ChatSource, ChatSources } from "@thenamespace/uikit";
const favicon = (url: string) =>
`/assets/favicons/${new URL(url).hostname.replaceAll(".", "-")}.png`;
const Assistant = ({ children }: { children: React.ReactNode }) => (
{children}
);
export const DemoGroupedExample = () => (
Answer synthesized from multiple sources.
3 sources
);
```
Use `ChatSources` to group multiple citations behind a collapsible trigger.
## Stacked Favicons
{/* DEMO chat-source-stacked-favicons */}
```tsx
"use client";
import { ChatMessage, ChatSource, ChatSources } from "@thenamespace/uikit";
const favicon = (url: string) =>
`/assets/favicons/${new URL(url).hostname.replaceAll(".", "-")}.png`;
const Assistant = ({ children }: { children: React.ReactNode }) => (
{children}
);
export const DemoStackedFaviconsExample = () => {
const sources = [
{ href: "https://www.reuters.com", label: "Reuters" },
{ href: "https://nypost.com", label: "New York Post" },
{ href: "https://www.foxsports.com", label: "Fox Sports" },
];
return (
Answer synthesized from multiple sources.
{sources.map((source) => (
})
))}
Sources
{sources.map((source) => (
);
};
```
For a compact source button, render stacked favicon avatars in the `ChatSources.Trigger`.
## Composable
{/* DEMO chat-source-composable */}
```tsx
"use client";
import { ChatMessage, ChatSource } from "@thenamespace/uikit";
const favicon = (url: string) =>
`/assets/favicons/${new URL(url).hostname.replaceAll(".", "-")}.png`;
const Assistant = ({ children }: { children: React.ReactNode }) => (
{children}
);
export const DemoComposableExample = () => (
React's documentation has a clear explanation of component
composition and state-driven rendering. The source chip below uses custom
trigger content with a fetched favicon.
React docs
);
```
Use compound parts when you need custom trigger content.
## Anatomy
```tsx
import {ChatSource, ChatSources} from "@thenamespace/uikit";
3 sources
```
## CSS Classes
- `.chat-source` - Source root
- `.chat-source__trigger` - Trigger wrapper
- `.chat-source__trigger-link` - Link or document pill
- `.chat-source__icon` - Favicon image or custom icon
- `.chat-source__icon-fallback` - Initial fallback for URL sources
- `.chat-source__document-icon` - Document source icon
- `.chat-source__preview` - Hover preview popover
- `.chat-sources` - Grouped source disclosure
- `.chat-sources__trigger` - Group trigger
- `.chat-sources__list` - Expanded source list
## API Reference
### ChatSource
| Prop | Type | Default | Description |
| --------------- | --------------------- | ----------------------- | -------------------------------------------------------------------------- |
| `href` | `string` | - | URL source link |
| `title` | `string` | domain | Display title |
| `description` | `string` | - | Enables and populates the hover preview |
| `enablePreview` | `boolean` | auto | Force-enable custom preview content or disable the automatic hover preview |
| `faviconUrl` | `string` | - | Favicon image shown in trigger and preview |
| `sourceType` | `'url' \| 'document'` | inferred | Source type |
| `children` | `ReactNode` | default trigger/preview | Custom source composition |
### ChatSource.Trigger
Renders the source pill trigger. Extends native anchor props for URL sources.
### ChatSource.Icon
Renders a custom icon or favicon.
| Prop | Type | Default | Description |
| ------------ | ----------- | ---------------- | ------------------- |
| `faviconUrl` | `string` | - | Favicon image URL |
| `children` | `ReactNode` | fallback initial | Custom icon element |
### ChatSource.Title
Renders the source title.
### ChatSource.Preview
Renders the hover preview content for URL sources with title or description. If you provide a
custom preview without root `title` or `description`, set `enablePreview` on `ChatSource` so the
required hover-card wrapper is mounted.
### ChatSources
Grouped source disclosure. Extends Namespace UIKit `Disclosure` props.
### ChatSources.Trigger
Renders the grouped source trigger.
### ChatSources.Content
Renders the expanded grouped source content.
### ChatSources.List
Renders the flex-wrapped source list.
# Chat Tool
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/chat-tool
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/chat-tool.mdx
> Collapsible tool-call cards for inputs, outputs, errors, approvals, and grouped tool activity.
## Usage
{/* DEMO chat-tool-default */}
```tsx
"use client";
import { ChatMessage, ChatTool } from "@thenamespace/uikit";
const Assistant = ({ children }: { children: React.ReactNode }) => (
{children}
);
export const DemoDefaultExample = () => (
Completed tool call with JSON args and result.
);
```
Use `ChatTool` to show tool calls emitted by an agent or assistant.
## Streaming
{/* DEMO chat-tool-streaming */}
```tsx
"use client";
import { ChatMessage, ChatTool } from "@thenamespace/uikit";
const Assistant = ({ children }: { children: React.ReactNode }) => (
{children}
);
export const DemoStreamingExample = () => (
);
```
Use streaming state while tool input is still being generated.
## Error
Use error state for failed tool calls.
## Approval
{/* DEMO chat-tool-approval */}
```tsx
"use client";
import { ChatMessage, ChatTool } from "@thenamespace/uikit";
const Assistant = ({ children }: { children: React.ReactNode }) => (
{children}
);
export const DemoApprovalExample = () => (
{}}
onReject={() => {}}
/>
);
```
Use approval state when a tool requires user confirmation.
## Grouped
{/* DEMO chat-tool-grouped */}
```tsx
"use client";
import { ChatMessage, ChatTool, ChatToolGroup } from "@thenamespace/uikit";
const Assistant = ({ children }: { children: React.ReactNode }) => (
{children}
);
export const DemoGroupedExample = () => (
2 tool calls
{["searchDocs", "fetchPage"].map((toolName) => (
);
```
Use `ChatToolGroup` to group consecutive tool calls.
## Composable
{/* DEMO chat-tool-composable */}
```tsx
"use client";
import { ChatMessage, ChatTool } from "@thenamespace/uikit";
const Assistant = ({ children }: { children: React.ReactNode }) => (
{children}
);
export const DemoComposableExample = () => (
);
```
Tool cards expose slots for custom trigger and content layouts.
## Anatomy
```tsx
import {ChatTool, ChatToolGroup} from "@thenamespace/uikit";
```
### Error State
{/* DEMO chat-tool-error-state */}
```tsx
"use client";
import { ChatMessage, ChatTool } from "@thenamespace/uikit";
const Assistant = ({ children }: { children: React.ReactNode }) => (
{children}
);
export const DemoErrorStateExample = () => (
);
```
## CSS Classes
- `.chat-tool` - Tool card root
- `.chat-tool__trigger` - Collapsible trigger
- `.chat-tool__content` - Disclosure content panel
- `.chat-tool__args` - Tool input content
- `.chat-tool__result` - Tool output content
- `.chat-tool__error` - Tool error content
- `.chat-tool-group` - Grouped tool root
## API Reference
### ChatTool
| Prop | Type | Default | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------- |
| `toolName` | `string` | - | Tool display name |
| `state` | `'input-streaming' \| 'input-available' \| 'output-available' \| 'output-error' \| 'requires-action'` | - | Tool state |
| `triggerPrefix` | `ReactNode` | - | Optional label rendered before `toolName` in preset mode |
| `input` | `unknown` | - | Tool input rendered as JSON in preset mode |
| `output` | `unknown` | - | Tool output rendered as JSON in preset mode |
| `argsText` | `string` | - | Preformatted tool input text, useful while streaming partial JSON |
| `errorText` | `string` | - | Error details rendered for `output-error` state |
| `onApprove` | `() => void` | - | Called by the preset approval action in `requires-action` state |
| `onReject` | `() => void` | - | Called by the preset rejection action in `requires-action` state |
| `defaultExpanded` | `boolean` | - | Open by default |
| `isExpanded` | `boolean` | - | Controlled expanded state |
### ChatTool.Trigger
Renders the collapsible tool trigger.
### ChatTool.Content
Renders the expanded tool body.
### ChatTool.Args, Result, Error, Approval
Semantic slots for tool input, output, error details, and approval controls.
### ChatToolGroup
Groups multiple `ChatTool` items. Extends Namespace UIKit `Disclosure` props.
# Checkbox Button Group
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/checkbox-button-group
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/checkbox-button-group.mdx
> A multi-selection button group with card-style checkboxes, icons, and custom indicators.
## Usage
{/* DEMO checkbox-button-group-default */}
```tsx
"use client";
import { CheckboxButtonGroup } from "@thenamespace/uikit";
import { Description } from "@thenamespace/uikit/description";
import { Label } from "@thenamespace/uikit/label";
const features = [
{
description: "Real-time threat detection and prevention",
value: "security",
},
{
description: "Cloud-based storage with automatic backups",
value: "storage",
},
{
description: "Usage reports and performance dashboards",
value: "analytics",
},
];
function FeatureContent({
description,
value,
}: {
description: string;
value: string;
}) {
return (
{description}
);
}
export const DemoDefaultExample = () => (
Choose all that apply to your project
{features.map((feature) => (
))}
);
```
## Anatomy
Import the CheckboxButtonGroup component and access all parts using dot notation.
```tsx
import { CheckboxButtonGroup } from "@thenamespace/uikit";
;
```
## Controlled
{/* DEMO checkbox-button-group-controlled */}
```tsx
"use client";
import { useState } from "react";
import { CheckboxButtonGroup } from "@thenamespace/uikit";
import { Description } from "@thenamespace/uikit/description";
import { Label } from "@thenamespace/uikit/label";
import { NumberValue } from "@thenamespace/uikit/number-value";
const addons = [
{
description: "Automated daily backups",
price: 5,
title: "Backups",
value: "backups",
},
{
description: "24/7 monitoring and alerts",
price: 12,
title: "Monitoring",
value: "monitoring",
},
{
description: "Priority email and chat support",
price: 8,
title: "Support",
value: "support",
},
];
function AddonContent({ addon }: { addon: (typeof addons)[number] }) {
return (
{addon.description}
/mo
);
}
export const DemoControlledExample = function Demo() {
const [value, setValue] = useState(["backups"]);
return (
Select the add-ons you need
{addons.map((addon) => (
))}
);
};
```
## Custom Indicator
{/* DEMO checkbox-button-group-custom-indicator */}
```tsx
"use client";
import { CheckboxButtonGroup } from "@thenamespace/uikit";
import { Description } from "@thenamespace/uikit/description";
import { Label } from "@thenamespace/uikit/label";
import { NumberValue } from "@thenamespace/uikit/number-value";
import { Icon } from "@/demos/icon";
export const DemoCustomIndicatorExample = () => (
{[
["product-updates", "Weekly product updates and tips", 4200],
["security-alerts", "Security alerts and maintenance notices", 8100],
["marketing", "Promotions, deals, and special offers", 2300],
].map(([value, description, subscribers]) => (
{description}
{" "}
subscribers
))}
);
```
## Disabled Group
{/* DEMO checkbox-button-group-disabled-group */}
```tsx
"use client";
import { CheckboxButtonGroup } from "@thenamespace/uikit";
import { Description } from "@thenamespace/uikit/description";
import { Label } from "@thenamespace/uikit/label";
const features = [
{
description: "Real-time threat detection and prevention",
value: "security",
},
{
description: "Cloud-based storage with automatic backups",
value: "storage",
},
{
description: "Usage reports and performance dashboards",
value: "analytics",
},
];
function FeatureContent({
description,
value,
}: {
description: string;
value: string;
}) {
return (
{description}
);
}
export const DemoDisabledGroupExample = () => (
Feature selection is temporarily unavailable.
{features.map((feature) => (
))}
);
```
## Grid Layout
{/* DEMO checkbox-button-group-grid-layout */}
```tsx
"use client";
import { CheckboxButtonGroup } from "@thenamespace/uikit";
import { Description } from "@thenamespace/uikit/description";
import { Label } from "@thenamespace/uikit/label";
import { NumberValue } from "@thenamespace/uikit/number-value";
const addons = [
{
description: "Automated daily backups",
price: 5,
title: "Backups",
value: "backups",
},
{
description: "24/7 monitoring and alerts",
price: 12,
title: "Monitoring",
value: "monitoring",
},
{
description: "Priority email and chat support",
price: 8,
title: "Support",
value: "support",
},
];
function AddonContent({ addon }: { addon: (typeof addons)[number] }) {
return (
{addon.description}
/mo
);
}
export const DemoGridLayoutExample = () => (
{addons.map((addon) => (
))}
);
```
## Icon Cards
{/* DEMO checkbox-button-group-icon-cards */}
```tsx
"use client";
import { CheckboxButtonGroup } from "@thenamespace/uikit";
import { Chip } from "@thenamespace/uikit/chip";
import { Description } from "@thenamespace/uikit/description";
import { Label } from "@thenamespace/uikit/label";
import { Icon } from "@/demos/icon";
const securityFeatures = [
{
badge: "Recommended",
description: "Two-factor authentication for all user accounts.",
icon: "solar:lock-password-outline",
title: "2FA",
value: "2fa",
},
{
description: "Encrypt data at rest and in transit.",
icon: "solar:shield-keyhole-outline",
title: "Encryption",
value: "encryption",
},
{
description: "Automated daily backups to secure cloud storage.",
icon: "solar:cloud-outline",
title: "Cloud Backup",
value: "cloud-backup",
},
{
description: "Real-time alerts for incidents and breaches.",
icon: "solar:notification-unread-outline",
title: "Alert System",
value: "alerts",
},
];
export const DemoIconCardsExample = () => (
{securityFeatures.map((feature) => (
{feature.description}
))}
);
```
## No Indicator
{/* DEMO checkbox-button-group-no-indicator */}
```tsx
"use client";
import { CheckboxButtonGroup } from "@thenamespace/uikit";
import { Description } from "@thenamespace/uikit/description";
import { Label } from "@thenamespace/uikit/label";
const features = [
{
description: "Real-time threat detection and prevention",
value: "security",
},
{
description: "Cloud-based storage with automatic backups",
value: "storage",
},
{
description: "Usage reports and performance dashboards",
value: "analytics",
},
];
function FeatureContent({
description,
value,
}: {
description: string;
value: string;
}) {
return (
{description}
);
}
export const DemoNoIndicatorExample = () => (
{features.map((feature) => (
))}
);
```
## Render Prop Children
{/* DEMO checkbox-button-group-render-prop-children */}
```tsx
"use client";
import { CheckboxButtonGroup } from "@thenamespace/uikit";
import { Description } from "@thenamespace/uikit/description";
import { Label } from "@thenamespace/uikit/label";
import { NumberValue } from "@thenamespace/uikit/number-value";
const addons = [
{
description: "Automated daily backups",
price: 5,
title: "Backups",
value: "backups",
},
{
description: "24/7 monitoring and alerts",
price: 12,
title: "Monitoring",
value: "monitoring",
},
{
description: "Priority email and chat support",
price: 8,
title: "Support",
value: "support",
},
];
export const DemoRenderPropChildrenExample = () => (
{addons.map((addon) => (
{() => (
<>
{addon.description}
/mo
)}
))}
);
```
## Subscription Plans
{/* DEMO checkbox-button-group-subscription-plans */}
```tsx
"use client";
import type { CSSProperties } from "react";
import { CheckboxButtonGroup } from "@thenamespace/uikit";
import { Button } from "@thenamespace/uikit/button";
import { Description } from "@thenamespace/uikit/description";
import { Label } from "@thenamespace/uikit/label";
import { Link } from "@thenamespace/uikit/link";
import { NumberValue } from "@thenamespace/uikit/number-value";
import { Icon } from "@/demos/icon";
const plans = [
[
"gold",
"Gold",
0.4,
12,
"Full suite of saving, investing, and learning tools for you and your family.",
],
["silver", "Silver", 0.2, 6, "Level up your saving and investing skills with even more tools."],
["bronze", "Bronze", 0.1, 3, "Investing tools to get you started on your financial journey."],
] as const;
export const DemoSubscriptionPlansExample = () => (
{plans.map(([value, title, daily, monthly, description]) => (
{({ isSelected }) => (
<>
{description}
)}
))}
);
```
## With Icons
{/* DEMO checkbox-button-group-with-icons */}
```tsx
"use client";
import { CheckboxButtonGroup } from "@thenamespace/uikit";
import { Description } from "@thenamespace/uikit/description";
import { Label } from "@thenamespace/uikit/label";
import { Icon } from "@/demos/icon";
const permissions = [
[
"content",
"Content Management",
"Create, edit, and delete content",
"solar:cloud-outline",
],
[
"users",
"User Administration",
"Manage team members and roles",
"solar:shield-keyhole-outline",
],
[
"analytics",
"Analytics Access",
"View and export reports",
"solar:database-outline",
],
[
"settings",
"Settings",
"Configure system preferences",
"solar:lock-outline",
],
];
export const DemoWithIconsExample = () => (
{permissions.map(([value, title, description, icon]) => (
{description}
))}
);
```
## With Ripple
{/* DEMO checkbox-button-group-with-ripple */}
```tsx
"use client";
import { CheckboxButtonGroup } from "@thenamespace/uikit";
import { Description } from "@thenamespace/uikit/description";
import { Label } from "@thenamespace/uikit/label";
import { PressableFeedback } from "@thenamespace/uikit/pressable-feedback";
export const DemoWithRippleExample = () => (
{["GitHub", "Slack", "Linear"].map((title) => (
Connect your {title} integration
))}
);
```
## CSS Classes
### Base Classes
- `.checkbox-button-group` - Base CheckboxGroup container with flex layout
### Layout Classes
- `.checkbox-button-group--grid` - Grid layout mode
### Element Classes
- `.checkbox-button-group__item` - Card-like checkbox button with border and selection ring
- `.checkbox-button-group__indicator` - Positioned top-right indicator (checkbox control or custom icon)
- `.checkbox-button-group__item-content` - Text/content area wrapping Checkbox.Content
- `.checkbox-button-group__item-icon` - Leading icon container
### Interactive States
- **Selected**: `[data-selected="true"]` on `.checkbox-button-group__item` (accent ring)
- **Focus visible**: `:focus-visible` or `[data-focus-visible="true"]` on `.checkbox-button-group__item` (focus ring)
- **Disabled**: `:disabled` or `[aria-disabled="true"]` on `.checkbox-button-group__item` (reduced opacity)
### CSS Variables
- `--checkbox-button-group-item-radius` - Border radius of items (default: `var(--radius-2xl)`)
## API Reference
### CheckboxButtonGroup
The root component. Wraps Namespace UIKit [CheckboxGroup](https://namespace.com/docs/react/components/checkbox-group) with card-style layout.
| Prop | Type | Default | Description |
| -------- | ------------------ | -------- | --------------------- |
| `layout` | `'flex' \| 'grid'` | `'flex'` | Layout mode for items |
Also supports all [Namespace UIKit CheckboxGroup](https://namespace.com/docs/react/components/checkbox-group) props.
### CheckboxButtonGroup.Item
A selectable card wrapping Namespace UIKit Checkbox. Supports render prop children for accessing selection state.
Also supports all [Namespace UIKit Checkbox](https://namespace.com/docs/react/components/checkbox) props.
### CheckboxButtonGroup.Indicator
Selection indicator positioned at the top-right of the item.
- **No children**: renders the default Namespace UIKit checkbox (Control + Indicator)
- **With children**: renders a custom icon that appears only when selected
| Prop | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------------- |
| `children` | `ReactNode` | - | Custom indicator icon (shown when selected) |
Also supports all native `span` HTML attributes.
### CheckboxButtonGroup.ItemContent
Content area for title and description text. Wraps Namespace UIKit `Checkbox.Content`.
| Prop | Type | Default | Description |
| ---------- | ----------- | ------- | ---------------- |
| `children` | `ReactNode` | - | Content elements |
Also supports all native `div` HTML attributes.
### CheckboxButtonGroup.ItemIcon
Leading icon container.
| Prop | Type | Default | Description |
| ---------- | ----------- | ------- | ------------ |
| `children` | `ReactNode` | - | Icon element |
Also supports all native `div` HTML attributes.
# CheckboxGroup
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/checkbox-group
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/checkbox-group.mdx
> A checkbox group component for managing multiple checkbox selections
## Import
```tsx
import {
CheckboxGroup,
Checkbox,
Label,
Description,
} from "@thenamespace/uikit";
```
### Usage
```tsx
import {Checkbox, CheckboxGroup, Description, Label} from "@thenamespace/uikit";
export function Basic() {
return (
Choose all that apply
Coding
Love building software
Design
Enjoy creating beautiful interfaces
Writing
Passionate about content creation
);
}
```
### Anatomy
Import the CheckboxGroup component and access all parts using dot notation.
```tsx
import {
CheckboxGroup,
Checkbox,
Label,
Description,
FieldError,
} from "@thenamespace/uikit";
export default () => (
Label {/* plain text — the clickable label */}
);
```
### In Surface
When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
```tsx
import {Checkbox, CheckboxGroup, Description, Label, Surface} from "@thenamespace/uikit";
export function OnSurface() {
return (
Choose all that apply
Coding
Love building software
Design
Enjoy creating beautiful interfaces
Writing
Passionate about content creation
);
}
```
### With Custom Indicator
```tsx
"use client";
import {Checkbox, CheckboxGroup, Description, Label} from "@thenamespace/uikit";
export function WithCustomIndicator() {
return (
Select the features you want
{({isSelected}) =>
isSelected ? (
) : null
}
Email notifications
Receive updates via email
{({isSelected}) =>
isSelected ? (
) : null
}
Newsletter
Get weekly newsletters
);
}
```
### Indeterminate
```tsx
"use client";
import {Checkbox, CheckboxGroup} from "@thenamespace/uikit";
import {useState} from "react";
export function Indeterminate() {
const [selected, setSelected] = useState(["coding"]);
const allOptions = ["coding", "design", "writing"];
return (
0 && selected.length < allOptions.length}
isSelected={selected.length === allOptions.length}
name="select-all"
onChange={(isSelected: boolean) => {
setSelected(isSelected ? allOptions : []);
}}
>
Select all
Coding
Design
Writing
);
}
```
### Controlled
```tsx
"use client";
import {Checkbox, CheckboxGroup, Label} from "@thenamespace/uikit";
import {useState} from "react";
export function Controlled() {
const [selected, setSelected] = useState(["coding", "design"]);
return (
Coding
Design
Writing
);
}
```
### Validation
```tsx
"use client";
import {Button, Checkbox, CheckboxGroup, FieldError, Form, Label} from "@thenamespace/uikit";
export function Validation() {
return (
);
}
```
### Disabled
```tsx
import {Checkbox, CheckboxGroup, Description, Label} from "@thenamespace/uikit";
export function Disabled() {
return (
Feature selection is temporarily disabled
Feature 1
This feature is coming soon
Feature 2
This feature is coming soon
);
}
```
### Features and Add-ons Example
```tsx
import {
Checkbox,
CheckboxGroup,
Description,
Label,
} from "@thenamespace/uikit";
import {
Comment01Icon,
HugeiconsIcon,
Mail01Icon,
Notification01Icon,
} from "@thenamespace/uikit/icons";
import clsx from "clsx";
export function FeaturesAndAddOns() {
const addOns = [
{
description: "Receive updates via email",
icon: Mail01Icon,
title: "Email Notifications",
value: "email",
},
{
description: "Get instant SMS notifications",
icon: Comment01Icon,
title: "SMS Alerts",
value: "sms",
},
{
description: "Browser and mobile push alerts",
icon: Notification01Icon,
title: "Push Notifications",
value: "push",
},
];
return (
Choose how you want to receive updates
);
}
```
### Custom Render Function
```tsx
"use client";
import {Checkbox, CheckboxGroup, Description, Label} from "@thenamespace/uikit";
export function CustomRenderFunction() {
return (
}>
Choose all that apply
Coding
Love building software
Design
Enjoy creating beautiful interfaces
Writing
Passionate about content creation
);
}
```
## Styling
### Passing Tailwind CSS classes
You can customize the CheckboxGroup component:
```tsx
import { CheckboxGroup, Checkbox, Label } from "@thenamespace/uikit";
function CustomCheckboxGroup() {
return (
Option 1
);
}
```
### Customizing the component classes
To customize the CheckboxGroup component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.checkbox-group {
@apply flex flex-col gap-2;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The CheckboxGroup component uses these CSS classes:
- `.checkbox-group` - Base checkbox group container
## API Reference
### CheckboxGroup Props
Inherits from [React Aria CheckboxGroup](https://react-spectrum.adobe.com/react-aria/CheckboxGroup.html).
| Prop | Type | Default | Description |
| -------------- | -------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------- |
| `value` | `string[]` | - | The current selected values (controlled) |
| `defaultValue` | `string[]` | - | The default selected values (uncontrolled) |
| `onChange` | `(value: string[]) => void` | - | Handler called when the selected values change |
| `isDisabled` | `boolean` | `false` | Whether the checkbox group is disabled |
| `isRequired` | `boolean` | `false` | Whether the checkbox group is required |
| `isReadOnly` | `boolean` | `false` | Whether the checkbox group is read only |
| `isInvalid` | `boolean` | `false` | Whether the checkbox group is in an invalid state |
| `name` | `string` | - | The name of the checkbox group, used when submitting an HTML form |
| `children` | `React.ReactNode \| (values: CheckboxGroupRenderProps) => React.ReactNode` | - | Checkbox group content or render prop |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### CheckboxGroupRenderProps
When using the render prop pattern, these values are provided:
| Prop | Type | Description |
| ------------ | ---------- | ------------------------------------------------- |
| `value` | `string[]` | The currently selected values |
| `isDisabled` | `boolean` | Whether the checkbox group is disabled |
| `isReadOnly` | `boolean` | Whether the checkbox group is read only |
| `isInvalid` | `boolean` | Whether the checkbox group is in an invalid state |
| `isRequired` | `boolean` | Whether the checkbox group is required |
# Checkbox
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/checkbox
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/checkbox.mdx
> Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected.
## Import
```tsx
import { Checkbox } from "@thenamespace/uikit";
```
### Usage
```tsx
import {Checkbox} from "@thenamespace/uikit";
export function Basic() {
return (
Accept terms and conditions
);
}
```
### Anatomy
Import the Checkbox component and access all parts using dot notation.
```tsx
import { Checkbox, Description, FieldError } from "@thenamespace/uikit";
export default () => (
Label {/* plain text — the clickable label + accessible name */}
);
```
### Disabled
```tsx
import {Checkbox, Description} from "@thenamespace/uikit";
export function Disabled() {
return (
Premium Feature
This feature is coming soon
);
}
```
### Default Selected
```tsx
import {Checkbox} from "@thenamespace/uikit";
export function DefaultSelected() {
return (
Enable email notifications
);
}
```
### Controlled
```tsx
"use client";
import {Checkbox} from "@thenamespace/uikit";
import {useState} from "react";
export function Controlled() {
const [isSelected, setIsSelected] = useState(true);
return (
Email notifications
);
}
```
### Indeterminate
```tsx
"use client";
import {Checkbox, Description} from "@thenamespace/uikit";
import {useState} from "react";
export function Indeterminate() {
const [isIndeterminate, setIsIndeterminate] = useState(true);
const [isSelected, setIsSelected] = useState(false);
return (
{
setIsSelected(selected);
setIsIndeterminate(false);
}}
>
Select all
Shows indeterminate state (dash icon)
);
}
```
### External Label
```tsx
import {Checkbox, Label} from "@thenamespace/uikit";
export function ExternalLabel() {
return (
);
}
```
### With Description
```tsx
import {Checkbox, Description} from "@thenamespace/uikit";
export function WithDescription() {
return (
Email notifications
Get notified when someone mentions you in a comment
);
}
```
### Render Props
```tsx
"use client";
import {Checkbox, Description} from "@thenamespace/uikit";
export function RenderProps() {
return (
{({isSelected}) => (
<>
{isSelected ? "Terms accepted" : "Accept terms"}
{isSelected ? "Thank you for accepting" : "Please read and accept the terms"}
)}
);
}
```
### Form Integration
```tsx
"use client";
import {Button, Checkbox} from "@thenamespace/uikit";
import React from "react";
export function Form() {
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
const formData = new FormData(e.target as HTMLFormElement);
alert(
`Form submitted with:\n${Array.from(formData.entries())
.map(([key, value]) => `${key}: ${value}`)
.join("\n")}`,
);
};
return (
);
}
```
### Invalid
```tsx
import {Checkbox, FieldError} from "@thenamespace/uikit";
export function Invalid() {
return (
I agree to the terms
You must accept the terms to continue
);
}
```
### Custom Indicator
```tsx
"use client";
import {Checkbox} from "@thenamespace/uikit";
export function CustomIndicator() {
return (
{({isSelected}) =>
isSelected ? (
) : null
}
Heart
{({isSelected}) =>
isSelected ? (
) : null
}
Plus
{({isIndeterminate}) =>
isIndeterminate ? (
) : null
}
Indeterminate
);
}
```
### Full Rounded
```tsx
import {Checkbox, Label} from "@thenamespace/uikit";
export function FullRounded() {
return (
Small size
Default size
Large size
Extra large size
);
}
```
### Variants
The Checkbox component supports two visual variants:
- **`primary`** (default) - Standard styling with default background, suitable for most use cases
- **`secondary`** - Lower emphasis variant, suitable for use in Surface components
```tsx
import {Checkbox, Description} from "@thenamespace/uikit";
export function Variants() {
return (
Primary checkbox
Standard styling with default background
Secondary checkbox
Lower emphasis variant for use in surfaces
);
}
```
### Custom Render Function
```tsx
"use client";
import {Checkbox, Label} from "@thenamespace/uikit";
export function CustomRenderFunction() {
return (
}>
);
}
```
## Styling
### Passing Tailwind CSS classes
You can customize individual Checkbox components:
```tsx
import { Checkbox } from "@thenamespace/uikit";
function CustomCheckbox() {
return (
Custom Checkbox
);
}
```
### Customizing the component classes
To customize the Checkbox component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.checkbox {
@apply inline-flex gap-3 items-center;
}
.checkbox__control {
@apply size-5 border-2 border-gray-400 rounded data-[selected=true]:bg-blue-500 data-[selected=true]:border-blue-500;
/* Animated background indicator */
&::before {
@apply bg-accent pointer-events-none absolute inset-0 z-0 origin-center scale-50 rounded-md opacity-0 content-[''];
transition:
scale 200ms linear,
opacity 200ms linear,
background-color 200ms ease-out;
}
/* Show indicator when selected */
&[data-selected="true"]::before {
@apply scale-100 opacity-100;
}
}
.checkbox__indicator {
@apply text-white;
}
.checkbox__content {
@apply items-center gap-3;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The Checkbox component uses these CSS classes:
- `.checkbox` - Base checkbox container (the field)
- `.checkbox__content` - Clickable label wrapping the control and label text
- `.checkbox__control` - Checkbox control box
- `.checkbox__indicator` - Checkbox checkmark indicator
### Interactive States
The checkbox supports both CSS pseudo-classes and data attributes for flexibility:
- **Selected**: `[data-selected="true"]` or `[aria-checked="true"]` (shows checkmark and background color change)
- **Indeterminate**: `[data-indeterminate="true"]` (shows indeterminate state with dash)
- **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` (shows error state with danger colors)
- **Hover**: `:hover` or `[data-hovered="true"]` on `Checkbox.Control` (button)
- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on the button (shows focus ring on control)
- **Disabled**: `[data-disabled="true"]` on the field (reduced opacity, including help text)
- **Pressed**: `:active` or `[data-pressed="true"]`
## API Reference
### Checkbox Props
Inherits from [React Aria CheckboxField](https://react-spectrum.adobe.com/react-aria/Checkbox.html).
| Prop | Type | Default | Description |
| -------------------- | -------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `isSelected` | `boolean` | `false` | Whether the checkbox is checked |
| `defaultSelected` | `boolean` | `false` | Whether the checkbox is checked by default (uncontrolled) |
| `isIndeterminate` | `boolean` | `false` | Whether the checkbox is in an indeterminate state |
| `isDisabled` | `boolean` | `false` | Whether the checkbox is disabled |
| `isInvalid` | `boolean` | `false` | Whether the checkbox is invalid |
| `isReadOnly` | `boolean` | `false` | Whether the checkbox is read only |
| `isRequired` | `boolean` | `false` | Whether the checkbox must be selected |
| `validate` | `(value: boolean) => ValidationError \| true \| null \| undefined` | - | Custom validation function |
| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA |
| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form |
| `value` | `string` | - | The value of the input element, used when submitting an HTML form |
| `onChange` | `(isSelected: boolean) => void` | - | Handler called when the checkbox value changes |
| `children` | `React.ReactNode \| (values: CheckboxFieldRenderProps) => React.ReactNode` | - | Checkbox content or field render prop |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### Checkbox.Content Props
The clickable `
# Chip
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/chip
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/chip.mdx
> Small informational badges for displaying labels, statuses, and categories
## Import
```tsx
import { Chip } from "@thenamespace/uikit";
```
## Anatomy
Import the Chip component and access all parts using dot notation.
> Plain-text children are automatically wrapped in ``.
```tsx
Label text
```
### Usage
```tsx
import {Chip} from "@thenamespace/uikit";
export function ChipBasic() {
return (
Default
Accent
Success
Warning
Danger
);
}
```
### Variants
```tsx
import React from "react";
import { Chip, Separator } from "@thenamespace/uikit";
import { CircleIcon, HugeiconsIcon } from "@thenamespace/uikit/icons";
export function ChipVariants() {
const sizes = ["lg", "md", "sm"] as const;
const variants = ["primary", "secondary", "tertiary", "soft"] as const;
const colors = ["accent", "default", "success", "warning", "danger"] as const;
return (
Information
Completed
Pending
Failed
Label
);
}
```
### Statuses
```tsx
import { Chip } from "@thenamespace/uikit";
import {
UnavailableIcon,
CheckmarkSquare02Icon,
CircleIcon,
InformationCircleIcon,
Alert01Icon,
HugeiconsIcon,
} from "@thenamespace/uikit/icons";
export function ChipStatuses() {
return (
Default
Active
Pending
Inactive
New Feature
Available
Beta
Deprecated
);
}
```
## Styling
### Passing Tailwind CSS classes
You can style the root container and individual slots:
```tsx
import { Chip } from "@thenamespace/uikit";
function CustomChip() {
return (
Custom Styled
);
}
```
### Customizing the component classes
To customize the Chip component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.chip {
@apply rounded-full text-xs;
}
.chip__label {
@apply font-medium;
}
.chip--accent {
@apply border-accent/20;
}
.chip--accent .chip__label {
@apply text-accent;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The Chip component uses these CSS classes:
#### Base Classes
- `.chip` - Base chip container styles
- `.chip__label` - Label text slot styles
#### Color Classes
- `.chip--accent` - Accent color variant
- `.chip--danger` - Danger color variant
- `.chip--default` - Default color variant
- `.chip--success` - Success color variant
- `.chip--warning` - Warning color variant
#### Variant Classes
- `.chip--primary` - Primary variant with filled background
- `.chip--secondary` - Secondary variant with border
- `.chip--tertiary` - Tertiary variant with transparent background
- `.chip--soft` - Soft variant with lighter background
#### Size Classes
- `.chip--sm` - Small size
- `.chip--md` - Medium size (default)
- `.chip--lg` - Large size
#### Compound Variant Classes
Chips support combining variant and color classes (e.g., `.chip--secondary.chip--accent`). The following combinations have default styles defined:
**Primary Variants:**
- `.chip--primary.chip--accent` - Primary accent combination with filled background
- `.chip--primary.chip--success` - Primary success combination with filled background
- `.chip--primary.chip--warning` - Primary warning combination with filled background
- `.chip--primary.chip--danger` - Primary danger combination with filled background
**Soft Variants:**
- `.chip--accent.chip--soft` - Soft accent combination with lighter background
- `.chip--success.chip--soft` - Soft success combination with lighter background
- `.chip--warning.chip--soft` - Soft warning combination with lighter background
- `.chip--danger.chip--soft` - Soft danger combination with lighter background
**Note:** You can apply custom styles to any variant-color combination (e.g., `.chip--secondary.chip--accent`, `.chip--tertiary.chip--success`) using the `@layer components` directive in your CSS.
## API Reference
### Chip Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------- | ------------- | ------------------------------------------- |
| `children` | `React.ReactNode` | - | Content to display inside the chip |
| `className` | `string` | - | Additional CSS classes for the root element |
| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Color variant of the chip |
| `variant` | `"primary" \| "secondary" \| "tertiary" \| "soft"` | `"secondary"` | Visual style variant |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the chip |
### Chip.Label Props
| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ----------------------------------------- |
| `children` | `React.ReactNode` | - | Label text content |
| `className` | `string` | - | Additional CSS classes for the label slot |
# CloseButton
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/close-button
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/close-button.mdx
> Button component for closing dialogs, modals, or dismissing content
## Import
```tsx
import { CloseButton } from "@thenamespace/uikit";
```
### Usage
```tsx
import {CloseButton} from "@thenamespace/uikit";
export function Default() {
return
Custom Icon
Alternative Icon
);
}
```
### Interactive
```tsx
"use client";
import {CloseButton} from "@thenamespace/uikit";
import {useState} from "react";
export function Interactive() {
const [count, setCount] = useState(0);
return (
setCount(count + 1)}
/>
Clicked: {count} times
);
}
```
## Styling
### Passing Tailwind CSS classes
```tsx
import { CloseButton } from "@thenamespace/uikit";
function CustomCloseButton() {
return (
Close
);
}
```
### Customizing the component classes
To customize the CloseButton component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.close-button {
@apply bg-red-100 text-red-800 hover:bg-red-200;
}
.close-button--custom {
@apply rounded-full border-2 border-red-300;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The CloseButton component uses these CSS classes:
#### Base Classes
- `.close-button` - Base component styles
#### Variant Classes
- `.close-button--default` - Default variant
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
- **Hover**: `:hover` or `[data-hovered="true"]`
- **Active/Pressed**: `:active` or `[data-pressed="true"]`
- **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
- **Disabled**: `:disabled` or `[aria-disabled="true"]`
## API Reference
### CloseButton Props
| Prop | Type | Default | Description |
| ------------ | ----------------------- | --------------- | ------------------------------------------- |
| `variant` | `"default"` | `"default"` | Visual variant of the button |
| `children` | `ReactNode \| function` | `
# Code Block
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/code-block
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/code-block.mdx
> Syntax-highlighted code blocks with language labels and copy actions for AI markdown.
## Usage
{/* DEMO code-block-default */}
```tsx
"use client";
import { CodeBlock } from "@thenamespace/uikit";
const code = `function greet(name: string) {
return \`Hello, \${name}!\`;
}
console.log(greet("Namespace UIKit"));`;
export const DemoDefaultExample = () => (
typescript
);
```
Use `CodeBlock` for fenced code output, tool snippets, and AI-generated examples.
## Anatomy
```tsx
import { CodeBlock } from "@thenamespace/uikit";
typescript
;
```
## CSS Classes
- `.code-block` - Root code block surface
- `.code-block__header` - Header row
- `.code-block__code` - Code scroll region
- `.code-block__copy-button` - Copy/check icon button
## API Reference
### CodeBlock
Root container. Also supports native `div` props.
### CodeBlock.Header
Header slot for language labels and actions. Also supports native `div` props.
### CodeBlock.Code
| Prop | Type | Default | Description |
| ---------- | -------- | ---------------- | ----------------- |
| `code` | `string` | - | Code to render |
| `language` | `string` | `'plaintext'` | Shiki language id |
| `theme` | `string` | `'github-light'` | Shiki theme |
Also supports native `div` props.
### CodeBlock.CopyButton
| Prop | Type | Default | Description |
| ------------ | -------- | ------------- | ------------------------ |
| `code` | `string` | - | Code copied to clipboard |
| `aria-label` | `string` | `'Copy code'` | Accessible label |
| `className` | `string` | - | Additional class |
# ColorArea
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/color-area
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/color-area.mdx
> A 2D color picker that allows users to select colors from a gradient area
## Import
```tsx
import { ColorArea } from "@thenamespace/uikit";
```
### Usage
```tsx
import {ColorArea} from "@thenamespace/uikit";
export function ColorAreaBasic() {
return (
);
}
```
### Anatomy
```tsx
import { ColorArea } from "@thenamespace/uikit";
export default () => (
);
```
### With Dots
```tsx
import {ColorArea} from "@thenamespace/uikit";
export function ColorAreaWithDots() {
return (
);
}
```
### Controlled
```tsx
"use client";
import type {Color} from "@thenamespace/uikit";
import {ColorArea, ColorSwatch, parseColor} from "@thenamespace/uikit";
import {useState} from "react";
export function ColorAreaControlled() {
const [color, setColor] = useState(parseColor("#9B80FF"));
return (
= {
hsb: [
{id: "hue", name: "Hue"},
{id: "saturation", name: "Saturation"},
{id: "brightness", name: "Brightness"},
],
hsl: [
{id: "hue", name: "Hue"},
{id: "saturation", name: "Saturation"},
{id: "lightness", name: "Lightness"},
],
rgb: [
{id: "red", name: "Red"},
{id: "green", name: "Green"},
{id: "blue", name: "Blue"},
],
};
export function ColorAreaSpaceAndChannels() {
const [colorSpace, setColorSpace] = useState("hsb");
const [color, setColor] = useState(() => parseColor("hsb(219, 58%, 93%)"));
const channels = channelsBySpace[colorSpace];
const defaultX = colorSpace === "rgb" ? "blue" : "saturation";
const defaultY =
colorSpace === "rgb" ? "green" : colorSpace === "hsl" ? "lightness" : "brightness";
const [xChannel, setXChannel] = useState(defaultX);
const [yChannel, setYChannel] = useState(defaultY);
const handleColorSpaceChange = (newSpace: Key | null) => {
if (!newSpace) return;
const space = newSpace as ColorSpace;
setColorSpace(space);
// Reset channels to appropriate defaults for the new color space
if (space === "rgb") {
setXChannel("blue");
setYChannel("green");
} else if (space === "hsl") {
setXChannel("saturation");
setYChannel("lightness");
} else {
setXChannel("saturation");
setYChannel("brightness");
}
};
// Filter out the other channel from options (can't have same channel on both axes)
const xChannelOptions = channels.filter((c) => c.id !== yChannel);
const yChannelOptions = channels.filter((c) => c.id !== xChannel);
return (
);
}
```
### Custom Render Function
```tsx
"use client";
import {ColorArea} from "@thenamespace/uikit";
export function CustomRenderFunction() {
return (
}
>
} />
);
}
```
## Styling
### Passing Tailwind CSS classes
```tsx
import { ColorArea } from "@thenamespace/uikit";
function CustomColorArea() {
return (
);
}
```
### Customizing the component classes
To customize the ColorArea component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.color-area {
@apply rounded-3xl;
}
.color-area__thumb {
@apply size-5 border-4;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ColorArea component uses these CSS classes:
#### Base Classes
- `.color-area` - Base styles with gradient background and inner shadow
- `.color-area--show-dots` - Adds dot grid overlay for precision picking
#### Element Classes
- `.color-area__thumb` - Draggable thumb indicator
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
- **Disabled**: `[data-disabled="true"]`
- **Focus**: `[data-focus-visible="true"]`
- **Dragging**: `[data-dragging="true"]` (thumb only)
## API Reference
### ColorArea Props
Inherits from [React Aria ColorArea](https://react-spectrum.adobe.com/react-aria/ColorArea.html).
| Prop | Type | Default | Description |
| -------------- | ---------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------- |
| `value` | `string \| Color` | - | The current color value (controlled) |
| `defaultValue` | `string \| Color` | - | The default color value (uncontrolled) |
| `onChange` | `(color: Color) => void` | - | Handler called when the color changes while dragging |
| `onChangeEnd` | `(color: Color) => void` | - | Handler called when the user stops dragging |
| `xChannel` | `ColorChannel` | `"saturation"` | Color channel for the horizontal axis |
| `yChannel` | `ColorChannel` | `"brightness"` | Color channel for the vertical axis |
| `colorSpace` | `ColorSpace` | - | The color space for the channels |
| `isDisabled` | `boolean` | `false` | Whether the color area is disabled |
| `showDots` | `boolean` | `false` | Whether to show the dot grid overlay |
| `className` | `string` | - | Additional CSS classes |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorArea.Thumb Props
| Prop | Type | Default | Description |
| ----------- | ----------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | Inline styles or render props function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
# ColorField
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/color-field
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/color-field.mdx
> Color input field with labels, descriptions, and validation built on React Aria ColorField
## Import
```tsx
import { ColorField, parseColor } from "@thenamespace/uikit";
```
### Usage
```tsx
"use client";
import type {Color} from "@thenamespace/uikit";
import {ColorField, ColorSwatch, Label, parseColor} from "@thenamespace/uikit";
import {useState} from "react";
export function Basic() {
const [color, setColor] = useState(parseColor("#0485F7"));
return (
);
}
```
### Anatomy
```tsx
import {
ColorField,
Label,
ColorSwatch,
Description,
FieldError,
parseColor,
} from "@thenamespace/uikit";
export default () => (
);
```
> **ColorField** combines label, color input, description, and error into a single accessible component.
### With Description
```tsx
import {ColorField, Description, Label} from "@thenamespace/uikit";
export function WithDescription() {
return (
Enter your brand's primary color
Used for highlights and CTAs
);
}
```
### Required Field
```tsx
import {ColorField, Description, Label} from "@thenamespace/uikit";
export function Required() {
return (
Required field
);
}
```
### Validation
Use `isInvalid` together with `FieldError` to surface validation messages.
```tsx
import {ColorField, FieldError, Label} from "@thenamespace/uikit";
export function Invalid() {
return (
Please enter a valid hex color
Invalid color format. Use hex (e.g., #FF5733)
);
}
```
### Channel Editing
ColorField supports editing individual color channels (hue, saturation, lightness, red, green, blue, alpha) by setting the `colorSpace` and `channel` props.
```tsx
"use client";
import type {Color} from "@thenamespace/uikit";
import {ColorField, ColorSwatch, Label, parseColor} from "@thenamespace/uikit";
import {useState} from "react";
export function ChannelEditing() {
const [color, setColor] = useState(parseColor("#7F007F"));
return (
%
%
(parseColor("#0485F7"));
return (
Current value: {value ? value.toString("hex") : "(empty)"}
);
}
```
### Disabled State
```tsx
"use client";
import {ColorField, Description, Label} from "@thenamespace/uikit";
export function Disabled() {
return (
This color field is disabled
This color field is disabled
);
}
```
### Full Width
```tsx
import {ColorField, Label} from "@thenamespace/uikit";
export function FullWidth() {
return (
);
}
```
### Variants
The ColorField.Group component supports two visual variants:
- **`primary`** (default) - Standard styling with shadow, suitable for most use cases
- **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components
```tsx
import {ColorField, Label} from "@thenamespace/uikit";
export function Variants() {
return (
);
}
```
### On Surface
When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on ColorField.Group to apply the lower emphasis variant suitable for surface backgrounds.
```tsx
import {ColorField, Description, Label, Surface} from "@thenamespace/uikit";
export function OnSurface() {
return (
Select your theme color
);
}
```
### Form Example
Complete form example with validation and submission handling.
```tsx
"use client";
import type {Color} from "@thenamespace/uikit";
import {Button, ColorField, ColorSwatch, Description, Form, Label} from "@thenamespace/uikit";
import {useState} from "react";
export function FormExample() {
const [value, setValue] = useState(null);
const [isSubmitting, setIsSubmitting] = useState(false);
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
if (!value) {
return;
}
setIsSubmitting(true);
// Simulate API call
setTimeout(() => {
console.log("Color submitted:", {color: value.toString("hex")});
setValue(null);
setIsSubmitting(false);
}, 1500);
};
return (
);
}
```
### Custom Render Function
```tsx
"use client";
import type {Color} from "@thenamespace/uikit";
import {ColorField, ColorSwatch, Label, parseColor} from "@thenamespace/uikit";
import {useState} from "react";
export function CustomRenderFunction() {
const [color, setColor] = useState(parseColor("#0485F7"));
return (
}
value={color}
onChange={setColor}
>
}>
);
}
```
## Styling
### Passing Tailwind CSS classes
```tsx
import {
ColorField,
Label,
ColorSwatch,
Description,
} from "@thenamespace/uikit";
function CustomColorField() {
return (
Select your brand's primary color.
);
}
```
### Customizing the component classes
ColorField has minimal default styling. Override the `.color-field` class to customize the container styling.
```css
@layer components {
.color-field {
@apply flex flex-col gap-1;
&[data-invalid="true"],
&[aria-invalid="true"] {
[data-slot="description"] {
@apply hidden;
}
}
[data-slot="label"] {
@apply w-fit;
}
[data-slot="description"] {
@apply px-1;
}
}
}
```
### CSS Classes
- `.color-field` – Root container with minimal styling (`flex flex-col gap-1`)
> **Note:** Child components ([Label](/docs/components/label), [Description](/docs/components/description), [FieldError](/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options. ColorField.Group styling is documented below in the API Reference section.
### Interactive States
ColorField automatically manages these data attributes based on its state:
- **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
- **Required**: `[data-required="true"]` - Applied when `isRequired` is true
- **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
- **Focus Within**: `[data-focus-within="true"]` - Applied when any child input is focused
## API Reference
### ColorField Props
ColorField inherits all props from React Aria's [ColorField](https://react-aria.adobe.com/ColorField.md) component.
#### Base Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------- |
| `children` | `React.ReactNode \| (values: ColorFieldRenderProps) => React.ReactNode` | - | Child components (Label, ColorField.Group, etc.) or render function. |
| `className` | `string \| (values: ColorFieldRenderProps) => string` | - | CSS classes for styling, supports render props. |
| `style` | `React.CSSProperties \| (values: ColorFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. |
| `fullWidth` | `boolean` | `false` | Whether the color field should take full width of its container |
| `id` | `string` | - | The element's unique identifier. |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
#### Value Props
| Prop | Type | Default | Description |
| -------------- | -------------------------------- | ------- | -------------------------------------- |
| `value` | `Color \| null` | - | Current value (controlled). |
| `defaultValue` | `Color \| null` | - | Default value (uncontrolled). |
| `onChange` | `(color: Color \| null) => void` | - | Handler called when the value changes. |
#### Channel Props
| Prop | Type | Default | Description |
| ------------ | -------------- | ------- | ---------------------------------------------------------------------------- |
| `colorSpace` | `ColorSpace` | - | The color space that the color field operates in when `channel` is provided. |
| `channel` | `ColorChannel` | - | The color channel to edit. If not provided, edits hex value. |
#### Validation Props
| Prop | Type | Default | Description |
| -------------------- | ---------------------------------------------------------------- | ---------- | -------------------------------------------------------------- |
| `isRequired` | `boolean` | `false` | Whether user input is required before form submission. |
| `isInvalid` | `boolean` | - | Whether the value is invalid. |
| `validate` | `(value: Color) => ValidationError \| true \| null \| undefined` | - | Custom validation function. |
| `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. |
#### State Props
| Prop | Type | Default | Description |
| ----------------- | --------- | ------- | -------------------------------------------------- |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed. |
| `isWheelDisabled` | `boolean` | - | Whether to disable changing the value with scroll. |
#### Form Props
| Prop | Type | Default | Description |
| ----------- | --------- | ------- | ---------------------------------------------------- |
| `name` | `string` | - | Name of the input element, for HTML form submission. |
| `autoFocus` | `boolean` | - | Whether the element should receive focus on render. |
#### Accessibility Props
| Prop | Type | Default | Description |
| ------------------ | -------- | ------- | ----------------------------------------------------- |
| `aria-label` | `string` | - | Accessibility label when no visible label is present. |
| `aria-labelledby` | `string` | - | ID of elements that label this field. |
| `aria-describedby` | `string` | - | ID of elements that describe this field. |
| `aria-details` | `string` | - | ID of elements with additional details. |
### Composition Components
ColorField works with these separate components that should be imported and used directly:
- **Label** - Field label component from `@thenamespace/uikit`
- **ColorField.Group** - Color input group component (documented below)
- **ColorField.Input** - Input element within ColorField.Group
- **ColorField.Prefix** / **ColorField.Suffix** - Prefix and suffix slots for the input group
- **ColorSwatch** - Color preview component from `@thenamespace/uikit`
- **Description** - Helper text component from `@thenamespace/uikit`
- **FieldError** - Validation error message from `@thenamespace/uikit`
Each of these components has its own props API. Use them directly within ColorField for composition:
```tsx
import {
ColorField,
Label,
ColorSwatch,
Description,
FieldError,
parseColor,
} from "@thenamespace/uikit";
Select your brand's primary color.
Please enter a valid color.
;
```
### Color Types
ColorField uses `Color` objects from React Aria Components:
```tsx
import { parseColor } from "@thenamespace/uikit";
// Parse from hex string
const color = parseColor("#3B82F6");
// Get hex string from color
const hex = color.toString("hex"); // "#3b82f6"
// Get RGB values
const rgb = color.toString("rgb"); // "rgb(59, 130, 246)"
// Use in ColorField
{/* ... */}
;
```
### ColorFieldRenderProps
When using render props with `className`, `style`, or `children`, these values are available:
| Prop | Type | Description |
| ---------------- | --------- | ----------------------------------------------- |
| `isDisabled` | `boolean` | Whether the field is disabled. |
| `isInvalid` | `boolean` | Whether the field is currently invalid. |
| `isReadOnly` | `boolean` | Whether the field is read-only. |
| `isRequired` | `boolean` | Whether the field is required. |
| `isFocused` | `boolean` | Whether the field is currently focused. |
| `isFocusWithin` | `boolean` | Whether any child element is focused. |
| `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). |
### ColorField.Group Props
ColorField.Group accepts all props from React Aria's `Group` component plus the following:
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `fullWidth` | `boolean` | `false` | Whether the color input group should take full width of its container |
| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorField.Input Props
ColorField.Input accepts all props from React Aria's `Input` component plus the following:
| Prop | Type | Default | Description |
| ------------- | -------- | ------- | -------------------------------------------------- |
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `placeholder` | `string` | - | Placeholder text shown when empty. |
### ColorField.Prefix Props
ColorField.Prefix accepts standard HTML `div` attributes:
| Prop | Type | Default | Description |
| ----------- | ----------- | ------- | -------------------------------------------------- |
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `children` | `ReactNode` | - | Content to display in the prefix slot. |
### ColorField.Suffix Props
ColorField.Suffix accepts standard HTML `div` attributes:
| Prop | Type | Default | Description |
| ----------- | ----------- | ------- | -------------------------------------------------- |
| `className` | `string` | - | Tailwind classes merged with the component styles. |
| `children` | `ReactNode` | - | Content to display in the suffix slot. |
## ColorField.Group Styling
### Customizing the component classes
The base classes power every instance. Override them once with `@layer components`.
```css
@layer components {
.color-input-group {
@apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;
&:hover,
&[data-hovered="true"] {
@apply bg-field-hover;
}
&[data-focus-within="true"],
&:focus-within {
@apply status-focused-field;
}
&[data-invalid="true"] {
@apply status-invalid-field;
}
&[data-disabled="true"],
&[aria-disabled="true"] {
@apply status-disabled;
}
}
.color-input-group__input {
@apply flex flex-1 items-center rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
}
.color-input-group__prefix,
.color-input-group__suffix {
@apply shrink-0 text-field-placeholder flex items-center;
}
}
```
### ColorField.Group CSS Classes
- `.color-input-group` – Root container styling
- `.color-input-group__input` – Input wrapper styling
- `.color-input-group__prefix` – Prefix element styling
- `.color-input-group__suffix` – Suffix element styling
### ColorField.Group Interactive States
- **Hover**: `:hover` or `[data-hovered="true"]`
- **Focus Within**: `[data-focus-within="true"]` or `:focus-within`
- **Invalid**: `[data-invalid="true"]` (also syncs with `aria-invalid`)
- **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]`
# Color Input Group
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/color-input-group
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/color-input-group.mdx
> Input-group primitives used to compose color fields and pickers.
Import this public entry point directly when composing lower-level UIKit parts.
```tsx
import * as ColorInputGroup from "@thenamespace/uikit/color-input-group";
```
See [color-field](./color-field) for complete composition examples and API guidance.
This entry point is also re-exported from `@thenamespace/uikit`. Direct imports make the dependency explicit and provide a stable location for advanced customization.
# ColorPicker
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/color-picker
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/color-picker.mdx
> A composable color picker that synchronizes color value between multiple color components
## Import
```tsx
import {
ColorPicker,
ColorArea,
ColorSlider,
ColorSwatch,
ColorField,
ColorSwatchPicker,
} from "@thenamespace/uikit";
```
### Usage
```tsx
import {ColorArea, ColorPicker, ColorSlider, ColorSwatch, Label} from "@thenamespace/uikit";
export function Basic() {
return (
);
}
```
### Anatomy
The ColorPicker is a composable component that combines multiple color components:
```tsx
import {
ColorPicker,
ColorArea,
ColorSlider,
ColorSwatch,
Label,
} from "@thenamespace/uikit";
export default () => (
);
```
### Controlled
```tsx
"use client";
import { useState } from "react";
import {
Button,
ColorArea,
ColorField,
ColorPicker,
ColorSlider,
ColorSwatch,
ColorSwatchPicker,
Label,
parseColor,
} from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
export function Controlled() {
const [color, setColor] = useState(parseColor("#325578"));
const colorPresets = [
"#ef4444",
"#f97316",
"#eab308",
"#22c55e",
"#06b6d4",
"#3b82f6",
"#8b5cf6",
"#ec4899",
"#f43f5e",
];
const shuffleColor = () => {
const randomHue = Math.floor(Math.random() * 360);
const randomSaturation = 50 + Math.floor(Math.random() * 50); // 50-100%
const randomLightness = 40 + Math.floor(Math.random() * 30); // 40-70%
setColor(parseColor(`hsl(${randomHue}, ${randomSaturation}%, ${randomLightness}%)`));
};
return (
{colorPresets.map((preset) => (
))}
);
}
```
### With Swatches
```tsx
import {
ColorArea,
ColorPicker,
ColorSlider,
ColorSwatch,
ColorSwatchPicker,
Label,
} from "@thenamespace/uikit";
export function WithSwatches() {
const presets = [
"#ef4444",
"#f97316",
"#eab308",
"#22c55e",
"#06b6d4",
"#3b82f6",
"#8b5cf6",
"#ec4899",
"#f43f5e",
];
return (
{presets.map((preset) => (
))}
);
}
```
### With Fields
Use `ColorField` to allow users to edit individual color channel values with a `Select` to switch between color spaces.
```tsx
"use client";
import type {ColorChannel, ColorSpace} from "@thenamespace/uikit";
import {
ColorArea,
ColorField,
ColorPicker,
ColorSlider,
ColorSwatch,
Label,
ListBox,
Select,
} from "@thenamespace/uikit";
import {useState} from "react";
export function WithFields() {
const [colorSpace, setColorSpace] = useState("hsl");
const colorChannelsByColorSpace: Record = {
hsb: ["hue", "saturation", "brightness"],
hsl: ["hue", "saturation", "lightness"],
rgb: ["red", "green", "blue"],
};
return (
);
}
```
### With Sliders
Use multiple `ColorSlider` components to adjust each channel of a color value.
```tsx
"use client";
import type {ColorChannel, ColorSpace} from "@thenamespace/uikit";
import {ColorPicker, ColorSlider, ColorSwatch, Label, ListBox, Select} from "@thenamespace/uikit";
import {useState} from "react";
export function WithSliders() {
const [colorSpace, setColorSpace] = useState("hsl");
const colorChannelsByColorSpace: Record = {
hsb: ["hue", "saturation", "brightness", "alpha"],
hsl: ["hue", "saturation", "lightness", "alpha"],
rgb: ["red", "green", "blue", "alpha"],
};
return (
);
}
```
## Styling
### Passing Tailwind CSS classes
```tsx
import {
ColorPicker,
ColorArea,
ColorSlider,
ColorSwatch,
Label,
} from "@thenamespace/uikit";
function CustomColorPicker() {
return (
);
}
```
### Customizing the component classes
To customize the ColorPicker component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.color-picker {
@apply inline-flex;
}
.color-picker__trigger {
@apply inline-flex items-center gap-4 rounded-lg;
}
.color-picker__popover {
@apply p-4 rounded-xl;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ColorPicker component uses these CSS classes:
#### Base Classes
- `.color-picker` - Base container
- `.color-picker__trigger` - Trigger button
- `.color-picker__popover` - Popover container
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
- **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
- **Disabled**: `:disabled` or `[data-disabled="true"]`
## API Reference
### ColorPicker Props
Inherits from [React Aria ColorPicker](https://react-spectrum.adobe.com/react-aria/ColorPicker.html).
| Prop | Type | Default | Description |
| -------------- | ------------------------ | ------- | ---------------------------------------------------- |
| `value` | `string \| Color` | - | The current color value (controlled) |
| `defaultValue` | `string \| Color` | - | The default color value (uncontrolled) |
| `onChange` | `(color: Color) => void` | - | Handler called when the color changes |
| `children` | `React.ReactNode` | - | Content of the color picker (Trigger, Popover, etc.) |
| `className` | `string` | - | Additional CSS classes |
### ColorPicker.Trigger Props
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------------------- | ------- | ------------------------------ |
| `children` | `React.ReactNode \| ((renderProps) => React.ReactNode)` | - | Trigger content or render prop |
| `className` | `string` | - | Additional CSS classes |
### ColorPicker.Popover Props
| Prop | Type | Default | Description |
| ----------- | ----------------- | --------------- | ------------------------ |
| `placement` | `Placement` | `"bottom left"` | Placement of the popover |
| `children` | `React.ReactNode` | - | Popover content |
| `className` | `string` | - | Additional CSS classes |
### Related Types
#### Color
Represents a color value. See [React Aria Color](https://react-spectrum.adobe.com/react-aria/ColorPicker.html#color) for full API.
| Method | Description |
| ---------------------------------- | ---------------------------------------------------------------------------- |
| `toString(format)` | Converts the color to a string in the given format (hex, rgb, hsl, hsb, css) |
| `toFormat(format)` | Converts the color to the given format and returns a new Color object |
| `getChannelValue(channel)` | Returns the numeric value for a given channel |
| `withChannelValue(channel, value)` | Sets the numeric value for a channel and returns a new Color |
#### parseColor
```tsx
import { parseColor } from "react-aria-components";
// Parse from string
const color = parseColor("#ff0000");
const hslColor = parseColor("hsl(0, 100%, 50%)");
```
# ColorSlider
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/color-slider
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/color-slider.mdx
> A color slider allows users to adjust an individual channel of a color value
## Import
```tsx
import { ColorSlider, Label } from "@thenamespace/uikit";
```
### Usage
```tsx
import {ColorSlider, Label} from "@thenamespace/uikit";
export function Basic() {
return (
);
}
```
### Anatomy
Import the ColorSlider component and access all parts using dot notation.
```tsx
import { ColorSlider, Label } from "@thenamespace/uikit";
export default () => (
);
```
### Vertical
```tsx
import {ColorSlider} from "@thenamespace/uikit";
export function Vertical() {
return (
);
}
```
### Disabled
```tsx
import {ColorSlider, Label} from "@thenamespace/uikit";
export function Disabled() {
return (
);
}
```
### Controlled
```tsx
"use client";
import {ColorSlider, ColorSwatch, Label} from "@thenamespace/uikit";
import {useState} from "react";
import {parseColor} from "react-aria-components";
export function Controlled() {
const [color, setColor] = useState(parseColor("hsl(200, 100%, 50%)"));
return (
);
}
```
### RGB Channels
You can also use RGB color space with red, green, and blue channels.
```tsx
"use client";
import {ColorSlider, ColorSwatch, Label} from "@thenamespace/uikit";
import {useState} from "react";
import {parseColor} from "react-aria-components";
export function RGBChannels() {
const [color, setColor] = useState(parseColor("rgb(255, 100, 50)"));
return (
}
>
);
}
```
## Styling
### Passing Tailwind CSS classes
```tsx
import { ColorSlider, Label } from "@thenamespace/uikit";
function CustomColorSlider() {
return (
);
}
```
### Customizing the component classes
To customize the ColorSlider component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.color-slider {
@apply flex flex-col gap-2;
}
.color-slider__output {
@apply text-muted text-sm;
}
.color-slider__track {
@apply relative h-5 w-full rounded-full;
}
.color-slider__thumb {
@apply size-4 rounded-full border-3 border-white shadow-overlay;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ColorSlider component uses these CSS classes:
#### Base Classes
- `.color-slider` - Base slider container
- `.color-slider__output` - Output element displaying current value
- `.color-slider__track` - Track element with color gradient
- `.color-slider__thumb` - Thumb element showing current color
#### State Classes
- `.color-slider[data-disabled="true"]` - Disabled slider state
- `.color-slider[data-orientation="vertical"]` - Vertical orientation
- `.color-slider__thumb[data-dragging="true"]` - Thumb being dragged
- `.color-slider__thumb[data-focus-visible="true"]` - Thumb keyboard focused
- `.color-slider__thumb[data-disabled="true"]` - Disabled thumb state
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
- **Hover**: `:hover` or `[data-hovered="true"]` on thumb
- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on thumb
- **Dragging**: `[data-dragging="true"]` on thumb
- **Disabled**: `:disabled` or `[data-disabled="true"]` on slider or thumb
## API Reference
### ColorSlider Props
Inherits from [React Aria ColorSlider](https://react-spectrum.adobe.com/react-aria/ColorSlider.html).
| Prop | Type | Default | Description |
| -------------- | ------------------------------------------------------------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------- |
| `channel` | `ColorChannel` | - | The color channel that the slider manipulates (hue, saturation, lightness, brightness, alpha, red, green, blue) |
| `colorSpace` | `ColorSpace` | - | The color space (hsl, hsb, rgb). Defaults to the color space of the value |
| `value` | `string \| Color` | - | The current color value (controlled) |
| `defaultValue` | `string \| Color` | - | The default color value (uncontrolled) |
| `onChange` | `(value: Color) => void` | - | Handler called when the value changes during dragging |
| `onChangeEnd` | `(value: Color) => void` | - | Handler called when dragging ends |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the slider |
| `isDisabled` | `boolean` | - | Whether the slider is disabled |
| `name` | `string` | - | The name of the input element for form submission |
| `aria-label` | `string` | - | Accessibility label for the slider |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Slider content or render function |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorSlider.Output Props
| Prop | Type | Default | Description |
| ----------- | ----------------------------- | ------- | --------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode \| RenderFunction` | - | Output content or render function |
### ColorSlider.Track Props
| Prop | Type | Default | Description |
| ----------- | --------------------------------- | ------- | -------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties \| RenderFunction` | - | Inline styles or render function |
| `children` | `ReactNode \| RenderFunction` | - | Track content or render function |
### ColorSlider.Thumb Props
| Prop | Type | Default | Description |
| ----------- | --------------------------------- | ------- | -------------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties \| RenderFunction` | - | Inline styles or render function |
| `children` | `ReactNode \| RenderFunction` | - | Thumb content or render function |
### RenderProps
When using render functions, these values are provided:
| Prop | Type | Description |
| ------------- | ---------------------------- | ------------------------------ |
| `state` | `ColorSliderState` | The state of the color slider |
| `color` | `Color` | The current color value |
| `orientation` | `"horizontal" \| "vertical"` | The orientation of the slider |
| `isDisabled` | `boolean` | Whether the slider is disabled |
## Accessibility
The ColorSlider component implements the ARIA slider pattern and provides:
- Full keyboard navigation support (Arrow keys, Home, End, Page Up/Down)
- Screen reader announcements for value changes
- Proper focus management
- Support for disabled states
- HTML form integration via hidden input elements
- Internationalization support with locale-aware value formatting
For more information, see the [React Aria ColorSlider documentation](https://react-spectrum.adobe.com/react-aria/ColorSlider.html).
# ColorSwatchPicker
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/color-swatch-picker
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/color-swatch-picker.mdx
> A list of color swatches that allows users to select a color from a predefined palette.
## Import
```tsx
import { ColorSwatchPicker, parseColor } from "@thenamespace/uikit";
```
### Usage
```tsx
import {ColorSwatchPicker} from "@thenamespace/uikit";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function Basic() {
return (
{colors.map((color) => (
))}
);
}
```
### Anatomy
Import the ColorSwatchPicker component and access all parts using dot notation.
```tsx
import { ColorSwatchPicker } from "@thenamespace/uikit";
export default () => (
);
```
### Variants
```tsx
import {ColorSwatchPicker} from "@thenamespace/uikit";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function Variants() {
return (
);
}
```
### Sizes
```tsx
import {ColorSwatchPicker} from "@thenamespace/uikit";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
export function Sizes() {
return (
{colors.map((color) => (
))}
);
}
```
### Default Value
```tsx
import {ColorSwatchPicker} from "@thenamespace/uikit";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function DefaultValue() {
return (
{colors.map((color) => (
))}
);
}
```
### Controlled
```tsx
"use client";
import {ColorSwatchPicker, parseColor} from "@thenamespace/uikit";
import {useState} from "react";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function Controlled() {
const [value, setValue] = useState(parseColor("#F43F5E"));
return (
{colors.map((color) => (
))}
);
}
```
### Disabled
```tsx
import {ColorSwatchPicker} from "@thenamespace/uikit";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function Disabled() {
return (
{colors.map((color) => (
))}
);
}
```
### Custom Indicator
```tsx
import { ColorSwatchPicker } from "@thenamespace/uikit";
import { FavouriteIcon, HugeiconsIcon } from "@thenamespace/uikit/icons";
export function CustomIndicator() {
const colors = [
"#F43F5E",
"#D946EF",
"#8B5CF6",
"#3B82F6",
"#06B6D4",
"#10B981",
"#84CC16",
];
return (
{colors.map((color) => (
))}
);
}
```
### Custom Render Function
```tsx
"use client";
import {ColorSwatchPicker} from "@thenamespace/uikit";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function CustomRenderFunction() {
return (
}>
{colors.map((color) => (
))}
);
}
```
## Styling
### Passing Tailwind CSS classes
You can customize the ColorSwatchPicker using className props:
```tsx
import { ColorSwatchPicker } from "@thenamespace/uikit";
function CustomColorSwatchPicker() {
return (
);
}
```
### Customizing the component classes
To customize the ColorSwatchPicker component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.color-swatch-picker {
@apply gap-4;
}
.color-swatch-picker__item {
@apply shadow-md;
}
.color-swatch-picker__swatch {
@apply border-2 border-white;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ColorSwatchPicker component uses these CSS classes:
#### Base & Structure
- `.color-swatch-picker` - Base container (flex layout)
- `.color-swatch-picker__item` - Individual swatch item wrapper
- `.color-swatch-picker__swatch` - The color swatch visual element
#### Size Classes
- `.color-swatch-picker--xs` - Extra small (16px)
- `.color-swatch-picker--sm` - Small (24px)
- `.color-swatch-picker--md` - Medium (32px, default)
- `.color-swatch-picker--lg` - Large (36px)
- `.color-swatch-picker--xl` - Extra large (40px)
#### Shape Variants
- `.color-swatch-picker--circle` - Circle shape (default)
- `.color-swatch-picker--square` - Square shape with rounded corners
#### Layout Classes
- `.color-swatch-picker--grid` - Horizontal wrapping layout (default)
- `.color-swatch-picker--stack` - Vertical stacked layout
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
- **Hover**: `:hover` or `[data-hovered="true"]` - Scale up to 1.1 (only when not selected)
- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` - Focus ring
- **Selected**: `[data-selected="true"]` - Inner border with same color as swatch
- **Disabled**: `[data-disabled="true"]` - Reduced opacity
## API Reference
### ColorSwatchPicker Props
Inherits from [React Aria ColorSwatchPicker](https://react-spectrum.adobe.com/react-aria/ColorSwatchPicker.html).
| Prop | Type | Default | Description |
| -------------- | ------------------------------------------------------------------------------------ | ---------- | ---------------------------------------------------------------- |
| `value` | `string \| Color` | - | The current selected color (controlled) |
| `defaultValue` | `string \| Color` | - | The default selected color (uncontrolled) |
| `onChange` | `(value: Color) => void` | - | Handler called when selection changes |
| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size of the swatches |
| `variant` | `"circle" \| "square"` | `"circle"` | Shape of the swatches |
| `layout` | `"grid" \| "stack"` | `"grid"` | Layout direction |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | ColorSwatchPicker.Item elements |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorSwatchPicker.Item Props
| Prop | Type | Default | Description |
| ------------ | ---------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------- |
| `color` | `string \| Color` | **Required** | The color of the swatch |
| `isDisabled` | `boolean` | `false` | Whether the item is disabled |
| `className` | `string` | - | Additional CSS classes |
| `children` | `React.ReactNode` | - | ColorSwatchPicker.Swatch element |
| `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. |
### ColorSwatchPicker.Swatch Props
| Prop | Type | Default | Description |
| ----------- | -------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
### parseColor
The `parseColor` function is re-exported from React Aria Components for convenience:
```tsx
import { parseColor } from "@thenamespace/uikit";
// Parse hex color
const red = parseColor("#ff0000");
// Parse RGB
const green = parseColor("rgb(0, 255, 0)");
// Parse HSL
const blue = parseColor("hsl(240, 100%, 50%)");
```
# ColorSwatch
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/color-swatch
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/color-swatch.mdx
> A visual preview of a color value with accessibility support
## Import
```tsx
import { ColorSwatch } from "@thenamespace/uikit";
```
### Usage
```tsx
import {ColorSwatch} from "@thenamespace/uikit";
export function ColorSwatchBasic() {
return (
}
/>
}
/>
}
/>
}
/>
}
/>
);
}
```
## Styling
### Passing Tailwind CSS classes
```tsx
import { ColorSwatch } from "@thenamespace/uikit";
function CustomColorSwatch() {
return ` | - | Overrides the default DOM element with a custom render function. |
### Style Render Props
When using the `style` prop as a function, you receive render props with access to the color:
```tsx
({
boxShadow: `0 4px 14px ${color.toString("css")}80`,
})}
/>
```
The `color` object provides methods like:
- `color.toString("css")` - Returns CSS color string
- `color.toString("hex")` - Returns hex color string
- `color.getChannelValue("alpha")` - Returns alpha channel value
# ComboBox
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/combo-box
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/combo-box.mdx
> A combo box combines a text input with a listbox, allowing users to filter a list of options to items matching a query
## Import
```tsx
import { ComboBox } from "@thenamespace/uikit";
```
### Usage
```tsx
"use client";
import {ComboBox, Input, Label, ListBox} from "@thenamespace/uikit";
export function Default() {
return (
Aardvark
Cat
Dog
Kangaroo
Panda
Snake
);
}
```
### Anatomy
Import the ComboBox component and access all parts using dot notation.
```tsx
import {
ComboBox,
Input,
Label,
Description,
Header,
ListBox,
Separator,
} from "@thenamespace/uikit";
export default () => (
);
```
### With Description
```tsx
"use client";
import {ComboBox, Description, Input, Label, ListBox} from "@thenamespace/uikit";
export function WithDescription() {
return (
Aardvark
Cat
Dog
Kangaroo
Panda
Snake
Search and select your favorite animal
);
}
```
### With Sections
```tsx
"use client";
import {ComboBox, Header, Input, Label, ListBox, Separator} from "@thenamespace/uikit";
export function WithSections() {
return (
North America
United States
Canada
Mexico
Europe
United Kingdom
France
Germany
Spain
Italy
Asia
Japan
China
India
South Korea
);
}
```
### With Disabled Options
```tsx
"use client";
import {ComboBox, Input, Label, ListBox} from "@thenamespace/uikit";
export function WithDisabledOptions() {
return (
Dog
Cat
Bird
Kangaroo
Elephant
Tiger
);
}
```
### Custom Indicator
```tsx
"use client";
import { ComboBox, Input, Label, ListBox } from "@thenamespace/uikit";
import { UnfoldMoreIcon, HugeiconsIcon } from "@thenamespace/uikit/icons";
export function CustomIndicator() {
return (
Aardvark
Cat
Dog
Kangaroo
Panda
Snake
);
}
```
### Required
```tsx
"use client";
import {Button, ComboBox, FieldError, Form, Input, Label, ListBox} from "@thenamespace/uikit";
export function Required() {
const onSubmit = (e: React.FormEvent) => {
e.preventDefault();
const formData = new FormData(e.currentTarget);
const data: Record = {};
formData.forEach((value, key) => {
data[key] = value.toString();
});
alert("Form submitted successfully!");
};
return (
);
}
```
### Custom Value
```tsx
"use client";
import {
Avatar,
AvatarFallback,
AvatarImage,
ComboBox,
Description,
Input,
Label,
ListBox,
} from "@thenamespace/uikit";
export function CustomValue() {
const users = [
{
avatarUrl: "/assets/avatars/blue.jpg",
email: "bob@namespace.ninja",
fallback: "B",
id: "1",
name: "Bob",
},
{
avatarUrl: "/assets/avatars/green.jpg",
email: "fred@namespace.ninja",
fallback: "F",
id: "2",
name: "Fred",
},
{
avatarUrl: "/assets/avatars/purple.jpg",
email: "martha@namespace.ninja",
fallback: "M",
id: "3",
name: "Martha",
},
{
avatarUrl: "/assets/avatars/red.jpg",
email: "john@namespace.ninja",
fallback: "J",
id: "4",
name: "John",
},
{
avatarUrl: "/assets/avatars/orange.jpg",
email: "jane@namespace.ninja",
fallback: "J",
id: "5",
name: "Jane",
},
];
return (
{users.map((user) => (
{user.fallback}
{user.email}
))}
);
}
```
### Controlled
```tsx
"use client";
import type {Key} from "@thenamespace/uikit";
import {ComboBox, Input, Label, ListBox} from "@thenamespace/uikit";
import {useState} from "react";
export function Controlled() {
const animals = [
{
id: "cat",
name: "Cat",
},
{
id: "dog",
name: "Dog",
},
{
id: "bird",
name: "Bird",
},
{
id: "fish",
name: "Fish",
},
{
id: "hamster",
name: "Hamster",
},
];
const [selectedKey, setSelectedKey] = useState("cat");
const selectedAnimal = animals.find((a) => a.id === selectedKey);
return (
setSelectedKey(key)}
>
{animals.map((animal) => (
{animal.name}
))}
);
}
```
### Controlled Input Value
```tsx
"use client";
import {ComboBox, Input, Label, ListBox} from "@thenamespace/uikit";
import {useState} from "react";
export function ControlledInputValue() {
const [inputValue, setInputValue] = useState("");
return (
Aardvark
Cat
Dog
Kangaroo
Panda
Snake
);
}
```
### Asynchronous Loading
```tsx
"use client";
import {
Collection,
ComboBox,
EmptyState,
Input,
Label,
ListBox,
ListBoxLoadMoreItem,
Spinner,
} from "@thenamespace/uikit";
import {useAsyncList} from "@react-stately/data";
interface Character {
name: string;
}
export function AsynchronousLoading() {
const list = useAsyncList({
async load({cursor, filterText, signal}) {
if (cursor) {
cursor = cursor.replace(/^http:\/\//i, "https://");
}
const res = await fetch(cursor || `https://swapi.py4e.com/api/people/?search=${filterText}`, {
signal,
});
const json = await res.json();
return {
cursor: json.next,
items: json.results,
};
},
});
return (
Nothing found. }>
{(item) => (
{item.name}
)}
);
}
```
### Custom Filtering
```tsx
"use client";
import {ComboBox, Input, Label, ListBox} from "@thenamespace/uikit";
export function CustomFiltering() {
const animals = [
{id: "cat", name: "Cat"},
{id: "dog", name: "Dog"},
{id: "bird", name: "Bird"},
{id: "fish", name: "Fish"},
{id: "hamster", name: "Hamster"},
];
return (
{
if (!inputValue) return true;
return text.toLowerCase().includes(inputValue.toLowerCase());
}}
>
{animals.map((animal) => (
{animal.name}
))}
);
}
```
### Allows Custom Value
```tsx
"use client";
import {ComboBox, Description, Input, Label, ListBox} from "@thenamespace/uikit";
export function AllowsCustomValue() {
return (
Aardvark
Cat
Dog
Kangaroo
Panda
Snake
You can type any animal name, even if it's not in the list
);
}
```
### Disabled
```tsx
"use client";
import {ComboBox, Input, Label, ListBox} from "@thenamespace/uikit";
export function Disabled() {
return (
Aardvark
Cat
Dog
Kangaroo
Panda
Snake
);
}
```
### Default Selected Key
```tsx
"use client";
import {ComboBox, Input, Label, ListBox} from "@thenamespace/uikit";
export function DefaultSelectedKey() {
return (
Aardvark
Cat
Dog
Kangaroo
Panda
Snake
);
}
```
### Full Width
```tsx
import {ComboBox, Input, Label, ListBox} from "@thenamespace/uikit";
export function FullWidth() {
return (
Aardvark
Cat
Dog
);
}
```
### In Surface
When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.
```tsx
"use client";
import {Button, ComboBox, FieldError, Form, Input, Label, ListBox, Surface} from "@thenamespace/uikit";
export function OnSurface() {
const onSubmit = (e: React.FormEvent) => {
e.preventDefault();
const formData = new FormData(e.currentTarget);
const data: Record = {};
formData.forEach((value, key) => {
data[key] = value.toString();
});
alert("Form submitted successfully!");
};
return (
);
}
```
### Menu Trigger
Use the `menuTrigger` prop to control when the popover opens:
- `focus` (default): popover opens when the user focuses the input
- `input`: popover opens when the user edits the input text
- `manual`: popover only opens when the user presses the trigger button or uses the arrow keys
```tsx
"use client";
import {ComboBox, Description, Input, Label, ListBox} from "@thenamespace/uikit";
export function MenuTrigger() {
return (
Aardvark
Cat
Dog
Kangaroo
Panda
Snake
Popover opens when the input is focused
Aardvark
Cat
Dog
Kangaroo
Panda
Snake
Popover opens when the user edits the input text
Aardvark
Cat
Dog
Kangaroo
Panda
Snake
Popover only opens when the trigger button is pressed or arrow keys are used
);
}
```
### Custom Render Function
```tsx
"use client";
import {ComboBox, Input, Label, ListBox} from "@thenamespace/uikit";
export function CustomRenderFunction() {
return (
}>
Aardvark
Cat
Dog
Kangaroo
Panda
Snake
);
}
```
## Styling
### Passing Tailwind CSS classes
```tsx
import { ComboBox, Input } from "@thenamespace/uikit";
function CustomComboBox() {
return (
Item 1
);
}
```
### Customizing the component classes
To customize the ComboBox component classes, you can use the `@layer components` directive.
[Learn
more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).
```css
@layer components {
.combo-box {
@apply flex flex-col gap-1;
}
.combo-box__input-group {
@apply relative inline-flex items-center;
}
.combo-box__trigger {
@apply absolute right-0 text-muted;
}
.combo-box__popover {
@apply rounded-lg border border-border bg-surface p-2;
}
}
```
Namespace UIKit follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.
### CSS Classes
The ComboBox component uses these CSS classes:
#### Base Classes
- `.combo-box` - Base ComboBox container
- `.combo-box__input-group` - Container for the input and trigger button
- `.combo-box__trigger` - The button that triggers the popover
- `.combo-box__popover` - The popover container
#### State Classes
- `.combo-box[data-invalid="true"]` - Invalid state
- `.combo-box[data-disabled="true"]` - Disabled ComboBox state
- `.combo-box__trigger[data-focus-visible="true"]` - Focused trigger state
- `.combo-box__trigger[data-disabled="true"]` - Disabled trigger state
- `.combo-box__trigger[data-open="true"]` - Open trigger state
### Interactive States
The component supports both CSS pseudo-classes and data attributes for flexibility:
- **Hover**: `:hover` or `[data-hovered="true"]` on trigger
- **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger
- **Disabled**: `:disabled` or `[data-disabled="true"]` on ComboBox
- **Open**: `[data-open="true"]` on trigger
## API Reference
### ComboBox Props
| Prop | Type | Default | Description |
| ----------------------- | ---------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputValue` | `string` | - | Current input value (controlled) |
| `defaultInputValue` | `string` | - | Default input value (uncontrolled) |
| `onInputChange` | `(value: string) => void` | - | Handler called when the input value changes |
| `selectedKey` | `Key \| null` | - | Current selected key (controlled) |
| `defaultSelectedKey` | `Key \| null` | - | Default selected key (uncontrolled) |
| `onSelectionChange` | `(key: Key \| null) => void` | - | Handler called when the selection changes |
| `items` | `Iterable` | - | The items to display in the listbox |
| `disabledKeys` | `Iterable` | - | Keys of disabled items |
| `defaultFilter` | `(text: string, inputValue: string) => boolean` | - | Custom filter function for filtering items |
| `isDisabled` | `boolean` | - | Whether the ComboBox is disabled |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user |
| `isRequired` | `boolean` | - | Whether user input is required |
| `isInvalid` | `boolean` | - | Whether the ComboBox value is invalid |
| `validate` | `(value: ComboBoxValidationValue) => ValidationError \| true \| null \| undefined` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead |
| `validationBehavior` | `"native" \| "aria"` | `"native"` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA |
| `name` | `string` | - | The name of the input, used when submitting an HTML form |
| `form` | `string` | - | The id of a `
# Command
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/command
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/command.mdx
> A command palette with fuzzy search, keyboard navigation, and nested groups for quick actions.
## Usage
{/* DEMO command-default */}
```tsx
"use client";
import { useState } from "react";
import { Button, Chip, Kbd } from "@thenamespace/uikit";
import { Command } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
const actions = [
["Create new file...", "lucide:file-plus-2"],
["Create new folder...", "lucide:folder-plus"],
["Assign to me", "lucide:user-round-pen"],
] as const;
const settings = [
["Preferences", "lucide:settings"],
["Change theme", "lucide:palette"],
["Keyboard shortcuts", "lucide:keyboard"],
] as const;
function Contents({ minimal = false }: { minimal?: boolean }) {
return (
<>
{minimal ? null : (
Home
)}
Esc
<>No results found.}>
{actions.map(([label, icon]) => (
))}
{minimal ? null : (
{settings.map(([label, icon]) => (
))}
)}
{minimal ? null : (
↑
↓
Navigate
↵
Select
)}
);
}
function Palette({
label = "Open Command Palette",
size = "md",
variant = "opaque",
children,
}: {
children?: React.ReactNode;
label?: string;
size?: "sm" | "md" | "lg";
variant?: "transparent" | "opaque" | "blur";
}) {
const [open, setOpen] = useState(false);
return (
<>
{children ??
);
}
export const DemoDefaultExample = () =>
;
```
## Clean
{/* DEMO command-clean */}
```tsx
"use client";
import { useState } from "react";
import { Button, Chip, Kbd } from "@thenamespace/uikit";
import { Command } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
const actions = [
["Create new file...", "lucide:file-plus-2"],
["Create new folder...", "lucide:folder-plus"],
["Assign to me", "lucide:user-round-pen"],
] as const;
const settings = [
["Preferences", "lucide:settings"],
["Change theme", "lucide:palette"],
["Keyboard shortcuts", "lucide:keyboard"],
] as const;
function Contents({ minimal = false }: { minimal?: boolean }) {
return (
<>
{minimal ? null : (
Home
)}
Esc
<>No results found.}>
{actions.map(([label, icon]) => (
))}
{minimal ? null : (
{settings.map(([label, icon]) => (
))}
)}
{minimal ? null : (
↑
↓
Navigate
↵
Select
)}
);
}
function Palette({
label = "Open Command Palette",
size = "md",
variant = "opaque",
children,
}: {
children?: React.ReactNode;
label?: string;
size?: "sm" | "md" | "lg";
variant?: "transparent" | "opaque" | "blur";
}) {
const [open, setOpen] = useState(false);
return (
<>
{children ??
);
}
export const DemoCleanExample = () => (
home
);
```
## Dev Toolbar
{/* DEMO command-dev-toolbar */}
```tsx
"use client";
import { useState } from "react";
import { Button, Chip, Kbd } from "@thenamespace/uikit";
import { Command } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
const actions = [
["Create new file...", "lucide:file-plus-2"],
["Create new folder...", "lucide:folder-plus"],
["Assign to me", "lucide:user-round-pen"],
] as const;
const settings = [
["Preferences", "lucide:settings"],
["Change theme", "lucide:palette"],
["Keyboard shortcuts", "lucide:keyboard"],
] as const;
function Contents({ minimal = false }: { minimal?: boolean }) {
return (
<>
{minimal ? null : (
Home
)}
Esc
<>No results found.}>
{actions.map(([label, icon]) => (
))}
{minimal ? null : (
{settings.map(([label, icon]) => (
))}
)}
{minimal ? null : (
↑
↓
Navigate
↵
Select
)}
);
}
function Palette({
label = "Open Command Palette",
size = "md",
variant = "opaque",
children,
}: {
children?: React.ReactNode;
label?: string;
size?: "sm" | "md" | "lg";
variant?: "transparent" | "opaque" | "blur";
}) {
const [open, setOpen] = useState(false);
return (
<>
{children ??
);
}
export const DemoDevToolbarExample = () => (
{[
"Feedback",
"Notifications",
"Feature Flags",
"Share Preview",
"Switch Branch",
"View Logs",
"Tracing",
].map((x) => (
))}
);
```
## Launcher
{/* DEMO command-launcher */}
```tsx
"use client";
import { useState } from "react";
import { Button, Chip, Kbd } from "@thenamespace/uikit";
import { Command } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
const actions = [
["Create new file...", "lucide:file-plus-2"],
["Create new folder...", "lucide:folder-plus"],
["Assign to me", "lucide:user-round-pen"],
] as const;
const settings = [
["Preferences", "lucide:settings"],
["Change theme", "lucide:palette"],
["Keyboard shortcuts", "lucide:keyboard"],
] as const;
function Contents({ minimal = false }: { minimal?: boolean }) {
return (
<>
{minimal ? null : (
Home
)}
Esc
<>No results found.}>
{actions.map(([label, icon]) => (
))}
{minimal ? null : (
{settings.map(([label, icon]) => (
))}
)}
{minimal ? null : (
↑
↓
Navigate
↵
Select
)}
);
}
function Palette({
label = "Open Command Palette",
size = "md",
variant = "opaque",
children,
}: {
children?: React.ReactNode;
label?: string;
size?: "sm" | "md" | "lg";
variant?: "transparent" | "opaque" | "blur";
}) {
const [open, setOpen] = useState(false);
return (
<>
{children ??
);
}
export const DemoLauncherExample = () => (
{[
"Design Tool",
"Project Tracker",
"Team Chat",
"Calendar",
"Settings",
].map((x, i) => (
))}
);
```
## Minimal
{/* DEMO command-minimal */}
```tsx
"use client";
import { useState } from "react";
import { Button, Chip, Kbd } from "@thenamespace/uikit";
import { Command } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
const actions = [
["Create new file...", "lucide:file-plus-2"],
["Create new folder...", "lucide:folder-plus"],
["Assign to me", "lucide:user-round-pen"],
] as const;
const settings = [
["Preferences", "lucide:settings"],
["Change theme", "lucide:palette"],
["Keyboard shortcuts", "lucide:keyboard"],
] as const;
function Contents({ minimal = false }: { minimal?: boolean }) {
return (
<>
{minimal ? null : (
Home
)}
Esc
<>No results found.}>
{actions.map(([label, icon]) => (
))}
{minimal ? null : (
{settings.map(([label, icon]) => (
))}
)}
{minimal ? null : (
↑
↓
Navigate
↵
Select
)}
);
}
function Palette({
label = "Open Command Palette",
size = "md",
variant = "opaque",
children,
}: {
children?: React.ReactNode;
label?: string;
size?: "sm" | "md" | "lg";
variant?: "transparent" | "opaque" | "blur";
}) {
const [open, setOpen] = useState(false);
return (
<>
{children ??
);
}
export const DemoMinimalExample = () => (
);
```
## Split View
{/* DEMO command-split-view */}
```tsx
"use client";
import { useState } from "react";
import { Button, Chip, Kbd } from "@thenamespace/uikit";
import { Command } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
const actions = [
["Create new file...", "lucide:file-plus-2"],
["Create new folder...", "lucide:folder-plus"],
["Assign to me", "lucide:user-round-pen"],
] as const;
const settings = [
["Preferences", "lucide:settings"],
["Change theme", "lucide:palette"],
["Keyboard shortcuts", "lucide:keyboard"],
] as const;
function Contents({ minimal = false }: { minimal?: boolean }) {
return (
<>
{minimal ? null : (
Home
)}
Esc
<>No results found.}>
{actions.map(([label, icon]) => (
))}
{minimal ? null : (
{settings.map(([label, icon]) => (
))}
)}
{minimal ? null : (
↑
↓
Navigate
↵
Select
)}
);
}
function Palette({
label = "Open Command Palette",
size = "md",
variant = "opaque",
children,
}: {
children?: React.ReactNode;
label?: string;
size?: "sm" | "md" | "lg";
variant?: "transparent" | "opaque" | "blur";
}) {
const [open, setOpen] = useState(false);
return (
<>
{children ??
);
}
function Split() {
const [selected, setSelected] = useState("Button");
const items = [
"Button",
"Input",
"Radio",
"Chip",
"Slider",
"Avatar",
"Switch",
];
return (
setSelected(String(key))}
>
{items.map((x) => (
))}
);
}
export const DemoSplitViewExample = () =>
Home
)}
Esc
<>No results found.}>
{actions.map(([label, icon]) => (
))}
{minimal ? null : (
{settings.map(([label, icon]) => (
))}
)}
{minimal ? null : (
↑
↓
Navigate
↵
Select
)}
);
}
function Palette({
label = "Open Command Palette",
size = "md",
variant = "opaque",
children,
}: {
children?: React.ReactNode;
label?: string;
size?: "sm" | "md" | "lg";
variant?: "transparent" | "opaque" | "blur";
}) {
const [open, setOpen] = useState(false);
return (
<>
{children ??
);
}
export const DemoMultipleSearchTermsExample = () => (
⌘ K
<>No results found.}>
{[
"Summarize this week's progress",
"Create a task for the team",
"Draft a project brief",
"Schedule a standup meeting",
].map((x) => (
))}
↑↓ Navigate · ↵ Select
);
```
## Sizes
{/* DEMO command-sizes */}
```tsx
"use client";
import { useState } from "react";
import { Button, Chip, Kbd } from "@thenamespace/uikit";
import { Command } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
const actions = [
["Create new file...", "lucide:file-plus-2"],
["Create new folder...", "lucide:folder-plus"],
["Assign to me", "lucide:user-round-pen"],
] as const;
const settings = [
["Preferences", "lucide:settings"],
["Change theme", "lucide:palette"],
["Keyboard shortcuts", "lucide:keyboard"],
] as const;
function Contents({ minimal = false }: { minimal?: boolean }) {
return (
<>
{minimal ? null : (
Home
)}
Esc
<>No results found.}>
{actions.map(([label, icon]) => (
))}
{minimal ? null : (
{settings.map(([label, icon]) => (
))}
)}
{minimal ? null : (
↑
↓
Navigate
↵
Select
)}
);
}
function SizesDemo() {
const [size, setSize] = useState<"sm" | "md" | "lg">("md");
const [open, setOpen] = useState(false);
return (
Home
)}
Esc
<>No results found.}>
{actions.map(([label, icon]) => (
))}
{minimal ? null : (
{settings.map(([label, icon]) => (
))}
)}
{minimal ? null : (
↑
↓
Navigate
↵
Select
)}
);
}
function Backdrops() {
const [variant, setVariant] = useState<"transparent" | "opaque" | "blur">(
"opaque",
);
const [open, setOpen] = useState(false);
return (
{items.map(({ color, label }) => (
);
}
export const DemoCustomTooltipExample = () => (
{label}
))}
Total
{total.toLocaleString()}
{kpis.map((kpi) => (
{kpi.label}
))}
);
```
## Multi Area
{/* DEMO area-chart-multi-area */}
```tsx
"use client";
import { AreaChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
const trafficData = [
{ month: "Jan", organic: 2000, paidAds: 1000 },
{ month: "Feb", organic: 5000, paidAds: 3000 },
{ month: "Mar", organic: 8000, paidAds: 5000 },
{ month: "Apr", organic: 7000, paidAds: 6000 },
{ month: "May", organic: 9500, paidAds: 4000 },
{ month: "Jun", organic: 8000, paidAds: 5500 },
{ month: "Jul", organic: 12000, paidAds: 7000 },
{ month: "Aug", organic: 11000, paidAds: 6500 },
{ month: "Sep", organic: 14000, paidAds: 8000 },
{ month: "Oct", organic: 13000, paidAds: 9000 },
{ month: "Nov", organic: 16000, paidAds: 10000 },
{ month: "Dec", organic: 15000, paidAds: 9500 },
];
function AxisSet() {
return (
<>
{kpi.label === "Total Revenue" ? (
{kpi.trend}
{kpi.suffix}
{items.map(({ color, label }) => (
);
}
export const DemoMultiAreaExample = () => (
{label}
))}
231,856
Sessions
{label}
);
}
export const DemoSparklineExample = () => (
{items.map(({ color, label }) => (
);
}
const stackedData = trafficData.map((item, index) => ({
...item,
direct: [
800, 1500, 2200, 1800, 2600, 2000, 3100, 2800, 3500, 3200, 4000, 3700,
][index]!,
referral: [
500, 1200, 2100, 2800, 3200, 2600, 4100, 3800, 4500, 5200, 5800, 5100,
][index]!,
}));
export const DemoStackedExample = () => {
const series = [
{ color: "var(--chart-4)", key: "organic", label: "Organic" },
{ color: "var(--chart-3)", key: "paidAds", label: "Paid Ads" },
{ color: "var(--chart-2)", key: "referral", label: "Referral" },
{ color: "var(--chart-1)", key: "direct", label: "Direct" },
];
return (
{label}
))}
Single Select Variants
Multiple Select Variants
Selected: {selectedState?.name || "None"}
Autocomplete is {isOpen ? "open" : "closed"}
{/* Color labels header */}
{variant.type === "img" ? (
<>
{color.charAt(0).toUpperCase()}
) : (
{variant.content}
)}
))}
))}
);
}
```
### Fallback Content
```tsx
import { Avatar } from "@thenamespace/uikit";
import { UserIcon, HugeiconsIcon } from "@thenamespace/uikit/icons";
export function Fallback() {
return (
{colors.map((color) => (
{color}
))}
{variant.label}
{colors.map((color, colorIndex) => (
{/* Text fallback */}
JD
{/* Icon fallback */}
{/* Fallback with delay */}
NA
{/* Custom styled fallback */}
GB
);
}
```
### Avatar Group
```tsx
import {Avatar} from "@thenamespace/uikit";
const users = [
{
id: 1,
image: "/assets/avatars/blue.jpg",
name: "John Doe",
},
{
id: 2,
image: "/assets/avatars/green.jpg",
name: "Kate Wilson",
},
{
id: 3,
image: "/assets/avatars/purple.jpg",
name: "Emily Chen",
},
{
id: 4,
image: "/assets/avatars/orange.jpg",
name: "Michael Brown",
},
{
id: 5,
image: "/assets/avatars/red.jpg",
name: "Olivia Davis",
},
];
export function Group() {
return (
{/* Basic avatar group */}
);
}
```
### Custom Styles
```tsx
import {Avatar} from "@thenamespace/uikit";
export function CustomStyles() {
return (
{users.slice(0, 4).map((user) => (
{user.name
.split(" ")
.map((n) => n[0])
.join("")}
))}
{/* Avatar group with counter */}
{users.slice(0, 3).map((user) => (
{user.name
.split(" ")
.map((n) => n[0])
.join("")}
))}
+{users.length - 3}
{/* Custom size with Tailwind classes */}
XL
{/* Square avatar */}
SQ
{/* Gradient border */}
GB
{/* Status indicator */}
ON
);
}
```
### Custom Image Component
Use `asChild` on `Avatar.Image` to compose with a custom image component. This example uses Next.js
`Image` for optimized loading. Pass `src` on `Avatar.Image` so it can track the loading state and
show the fallback until the image is ready.
```tsx
import Image from "next/image";
import { Avatar } from "@thenamespace/uikit";
const SRC = "/assets/avatars/blue.jpg";
export function CustomImageComponent() {
return (
{colors.map((color) => (
JD
))}
);
}
```
### Sizes
```tsx
import {Avatar, Badge} from "@thenamespace/uikit";
const AVATAR_URL = "/assets/avatars/green.jpg";
export function BadgeSizes() {
const sizes = ["sm", "md", "lg"] as const;
return (
{sizes.map((size) => (
JD
5
))}
);
}
```
### Variants
```tsx
import {Avatar, Badge, Separator} from "@thenamespace/uikit";
import React from "react";
const AVATAR_URL = "/assets/avatars/green.jpg";
export function BadgeVariants() {
const variants = ["primary", "secondary", "soft"] as const;
const colors = ["accent", "default", "success", "warning", "danger"] as const;
return (
{variants.map((variant, index) => (
{index < variants.length - 1 &&
))}
);
}
```
### Placements
```tsx
import {Avatar, Badge} from "@thenamespace/uikit";
const AVATAR_URL = "/assets/avatars/green.jpg";
export function BadgePlacements() {
const placements = ["top-right", "top-left", "bottom-right", "bottom-left"] as const;
return (
{variant}
{colors.map((color) => (
JD
5
))}
{placements.map((placement) => (
JD
{placement}
))}
);
}
```
### With Content
Badge supports text, numbers, and icons as content. When no children are provided, it renders as a dot indicator.
```tsx
import { Avatar, Badge } from "@thenamespace/uikit";
import { Notification01Icon, HugeiconsIcon } from "@thenamespace/uikit/icons";
const AVATAR_URL = "/assets/avatars/green.jpg";
export function BadgeWithContent() {
return (
{colors.map((color) => (
JD
))}
);
}
```
## Styling
### Passing Tailwind CSS classes
You can style the root container and individual slots:
```tsx
import { Badge, Avatar } from "@thenamespace/uikit";
function CustomBadge() {
return (
{items.map(({ color, label }) => (
);
}
export const DemoComparisonExample = () => {
const data = [
{ current: 120, day: "Mon", previous: 90 },
{ current: 180, day: "Tue", previous: 150 },
{ current: 150, day: "Wed", previous: 170 },
{ current: 210, day: "Thu", previous: 140 },
{ current: 190, day: "Fri", previous: 160 },
{ current: 80, day: "Sat", previous: 100 },
{ current: 60, day: "Sun", previous: 70 },
];
return (
{label}
))}
Total
${total.toLocaleString()}
{items.map(({ color, label }) => (
);
}
const channelSeries = [
{ color: "var(--chart-3)", key: "online", label: "Online" },
{ color: "var(--chart-2)", key: "retail", label: "Retail" },
{ color: "var(--chart-1)", key: "direct", label: "Direct" },
] as const;
export const DemoGroupedExample = () => (
{label}
))}
{items.map(({ color, label }) => (
);
}
const energy = [
{ day: "Mon", high: 180, low: 120, medium: 280 },
{ day: "Tue", high: 220, low: 150, medium: 320 },
{ day: "Wed", high: 150, low: 180, medium: 250 },
{ day: "Thu", high: 180, low: 140, medium: 290 },
{ day: "Fri", high: 190, low: 160, medium: 270 },
{ day: "Sat", high: 210, low: 130, medium: 240 },
{ day: "Sun", high: 240, low: 170, medium: 300 },
];
export const DemoHorizontalStackedExample = () => (
{label}
))}
580/280 kcal
{items.map(({ color, label }) => (
);
}
const plans = [
{ enterprise: 12000, pro: 8000, quarter: "Q1", starter: 4000 },
{ enterprise: 15000, pro: 10000, quarter: "Q2", starter: 5000 },
{ enterprise: 18000, pro: 12000, quarter: "Q3", starter: 6000 },
{ enterprise: 22000, pro: 14000, quarter: "Q4", starter: 7000 },
];
export const DemoStackedExample = () => (
{label}
))}
{/* Single button with dropdown */}
All commits from this branch will be added to the base
branch
The 14 commits from this branch will be combined into one
commit in the base branch
The 14 commits from this branch will be rebased and added to
the base branch
{/* Individual buttons */}
{/* Previous/Next Button Group */}
{/* Content Selection Button Group */}
{/* Text Alignment Button Group */}
{/* Icon-Only Alignment Button Group */}
);
}
```
### Anatomy
Import the ButtonGroup component and access all parts using dot notation.
```tsx
import { ButtonGroup, Button } from "@thenamespace/uikit";
export default () => (
Primary
Secondary
Tertiary
Outline
Ghost
Danger
Small
Medium (default)
Large
Horizontal
Vertical
With icons
Icon only buttons
All buttons disabled
Group disabled, but one button overrides
Has bookings
Weekend/Unavailable
{selectedDate ? (
) : null}
Use for less important content or nested cards
The default card variant for most use cases
Use to draw moderate attention
Use for primary or featured content
Only 10 spots
Submission ends Oct 10.
{/* Row 1: Large Product Card - Available Soon */}
Become an ACME Creator!
Lorem ipsum dolor sit amet consectetur. Sed arcu donec id
aliquam dolor sed amet faucibus etiam.
{/* Row 2 */}
Only 10 spots
Submission ends Oct 10.
{/* Left Column */}
{/* Background image */}
{/* Header */}
NEO
Home Robot
{/* Footer */}
{/* Row 3 */}
{/* Top Card */}
Go to settings
{/* Bottom cards */}
{/* Right Column */}
PAYMENT
You can now withdraw on crypto
Add your wallet in settings to withdraw
{/* Left Card */}
JK
JK
{/* Right Card */}
AB
M
Indie Hackers
148 members
By John
AI Builders
362 members
By Martha
{/* Header */}
Available soon
Get notified
{/* Left Column: Card */}
{/* Right Column: Cards Stack */}
NEO
$499/m
{/* 1 */}
Bridging the Future
Today, 6:30 PM
{/* 2 */}
Avocado Hackathon
Wed, 4:30 PM
{/* 3 */}
Sound Electro | Beyond art
Fri, 8:00 PM
Content with custom styling
Slide {current} of {count}
Selected: {color.toString("hex").toUpperCase()}
{[
["Accent", accent, setAccent],
["Success", success, setSuccess],
["Danger", danger, setDanger],
].map(([label, color, setColor]) => (
{label as string}
))}
);
};
```
## Variants
{/* DEMO cell-color-picker-variants */}
```tsx
"use client";
import { CellColorPicker } from "@thenamespace/uikit";
import { ColorArea } from "@thenamespace/uikit/color-area";
import { ColorSlider } from "@thenamespace/uikit/color-slider";
import { Label } from "@thenamespace/uikit/label";
function PickerControls() {
return (
<>
{(["default", "secondary"] as const).map((variant) => (
);
```
## With Presets
{/* DEMO cell-color-picker-with-presets */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import { useState } from "react";
import { CellColorPicker } from "@thenamespace/uikit";
import { ColorArea } from "@thenamespace/uikit/color-area";
import { ColorSlider } from "@thenamespace/uikit/color-slider";
import { ColorSwatchPicker } from "@thenamespace/uikit/color-swatch-picker";
import { Input } from "@thenamespace/uikit/input";
import { Label } from "@thenamespace/uikit/label";
import { parseColor } from "react-aria-components";
function PickerControls() {
return (
<>
{variant}
))}
Selected: {selected?.name ?? "None"}
Font Family
);
```
## Settings Group
{/* DEMO cell-select-settings-group */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import { useState } from "react";
import { CellSelect } from "@thenamespace/uikit";
import { ListBox } from "@thenamespace/uikit/list-box";
const themes = [
{ id: "default", name: "Default" },
{ id: "dark", name: "Dark" },
{ id: "system", name: "System" },
];
const settings = [
{ label: "Theme", options: themes, value: "default" },
{
label: "Language",
options: [
{ id: "en", name: "English" },
{ id: "es", name: "Spanish" },
{ id: "fr", name: "French" },
],
value: "en",
},
{
label: "Font size",
options: [
{ id: "sm", name: "Small" },
{ id: "md", name: "Medium" },
{ id: "lg", name: "Large" },
],
value: "md",
},
];
function SettingSelect({ setting }: { setting: (typeof settings)[number] }) {
const [value, setValue] = useState(setting.value);
return (
{settings.map((setting) => (
);
```
## Variants
{/* DEMO cell-select-variants */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import { useState } from "react";
import { CellSelect } from "@thenamespace/uikit";
import { ListBox } from "@thenamespace/uikit/list-box";
const themes = [
{ id: "default", name: "Default" },
{ id: "dark", name: "Dark" },
{ id: "system", name: "System" },
];
function ThemeItems() {
return themes.map((item) => (
{(["default", "secondary"] as const).map((variant) => (
);
```
## CSS Classes
### Base Classes
- `.cell-select` - Root wrapper
### Element Classes
- `.cell-select__trigger` - The visible cell row (wraps Select.Trigger)
- `.cell-select__trigger--default` - Default variant trigger styling
- `.cell-select__trigger--secondary` - Secondary variant trigger styling
- `.cell-select__label` - Leading text label
- `.cell-select__value` - Selected value display
- `.cell-select__indicator` - Chevron icon
- `.cell-select__popover` - Dropdown panel
## API Reference
### CellSelect
The root component. Wraps Namespace UIKit [Select](https://namespace.com/docs/react/components/select) with cell-style layout.
| Prop | Type | Default | Description |
| --------- | -------------------------- | ----------- | -------------------- |
| `variant` | `'default' \| 'secondary'` | `'default'` | Visual style variant |
Also supports all [Namespace UIKit Select](https://namespace.com/docs/react/components/select) props except `variant`.
### CellSelect.Trigger
The visible cell row containing label, value, and indicator.
Also supports all Namespace UIKit `Select.Trigger` props.
### CellSelect.Label
Leading text label rendered as a `span`.
| Prop | Type | Default | Description |
| ---------- | ----------- | ------- | ----------- |
| `children` | `ReactNode` | - | Label text |
Also supports all native `span` HTML attributes.
### CellSelect.Value
Display of the currently selected value.
Also supports all Namespace UIKit `Select.Value` props.
### CellSelect.Indicator
Chevron icon. Defaults to a `ChevronsExpandVertical` icon when no children are provided.
| Prop | Type | Default | Description |
| ---------- | ----------- | ------- | --------------------- |
| `children` | `ReactNode` | - | Custom indicator icon |
Also supports all Namespace UIKit `Select.Indicator` props.
### CellSelect.Popover
Dropdown panel for selection options.
| Prop | Type | Default | Description |
| ----------- | ----------- | -------------- | ----------------------------------------- |
| `placement` | `Placement` | `'bottom end'` | Popover placement relative to the trigger |
Also supports all Namespace UIKit `Select.Popover` props.
{variant}
))}
Value: {value.toFixed(2)}
Density
Corners
{(["default", "secondary"] as const).map((variant) => (
);
```
## CSS Classes
### Base Classes
- `.cell-slider` - Root wrapper
### Element Classes
- `.cell-slider__track` - The visible cell row (Slider.Track)
- `.cell-slider__track--default` - Default variant track styling
- `.cell-slider__track--secondary` - Secondary variant track styling
- `.cell-slider__fill` - Accent tint showing the current value
- `.cell-slider__thumb` - Transparent hit area with a `::after` pill indicator
- `.cell-slider__label` - Leading text label (absolutely positioned left)
- `.cell-slider__output` - Value display (absolutely positioned right)
## API Reference
### CellSlider
The root component. Wraps Namespace UIKit [Slider](https://namespace.com/docs/react/components/slider) with cell-style layout. Always renders in horizontal orientation.
| Prop | Type | Default | Description |
| --------- | -------------------------- | ----------- | -------------------- |
| `variant` | `'default' \| 'secondary'` | `'default'` | Visual style variant |
Also supports all [Namespace UIKit Slider](https://namespace.com/docs/react/components/slider) props except `variant` and `orientation`.
### CellSlider.Track
The visible cell row serving as the slider track. Contains fill, thumb, label, and output as children.
Also supports all Namespace UIKit `Slider.Track` props.
### CellSlider.Fill
Subtle accent tint showing the current slider value.
Also supports all Namespace UIKit `Slider.Fill` props.
### CellSlider.Thumb
Transparent hit area for drag and keyboard accessibility. The visible indicator is a `::after` pseudo-element (thin 3px pill).
Also supports all Namespace UIKit `Slider.Thumb` props.
### CellSlider.Label
Leading text label, absolutely positioned on the left.
| Prop | Type | Default | Description |
| ---------- | ----------- | ------- | ----------- |
| `children` | `ReactNode` | - | Label text |
Also supports all native `span` HTML attributes.
### CellSlider.Output
Value display, absolutely positioned on the right.
Also supports all Namespace UIKit `Slider.Output` props.
{variant}
))}
Animations: {selected ? "On" : "Off"}
Try the new sidebar
New
Keep your pages, meetings, and AI within reach.
{(["default", "secondary"] as const).map((variant) => (
);
```
## CSS Classes
### Base Classes
- `.cell-switch` - Root wrapper (renders as a `label` via Namespace UIKit Switch)
### Element Classes
- `.cell-switch__trigger` - The visible cell row container
- `.cell-switch__trigger--default` - Default variant trigger styling
- `.cell-switch__trigger--secondary` - Secondary variant trigger styling
- `.cell-switch__label` - Leading text label
- `.cell-switch__control` - Switch control wrapper
- `.cell-switch__control--secondary` - Secondary variant control styling
### Variant Classes
- `.cell-switch--secondary` - Secondary variant on the root
## API Reference
### CellSwitch
The root component. Wraps Namespace UIKit [Switch](https://namespace.com/docs/react/components/switch) with cell-style layout. Clicking anywhere in the cell toggles the switch.
| Prop | Type | Default | Description |
| --------- | -------------------------- | ----------- | -------------------- |
| `variant` | `'default' \| 'secondary'` | `'default'` | Visual style variant |
Also supports all [Namespace UIKit Switch](https://namespace.com/docs/react/components/switch) props except `variant`.
### CellSwitch.Trigger
The visible cell row containing the label and switch control. Renders Namespace UIKit `Switch.Content` (a `
{variant}
))}
{children}
The user wants a simple login page. This is a straightforward UI task - I should create a clean login form. Let me generate some design inspiration first to ensure it looks good, then build the page.
Now let me check the existing UI components available:
Scanning 56 files
I have all the components I need. Let me read the button, input, card, and label components to understand their APIs:
Now I have all the information I need. Let me create a clean, simple login page using the existing design system components:
{children}
The user wants a simple login page. This is a straightforward UI task - I should create a clean login form. Let me generate some design inspiration first to ensure it looks good, then build the page.
Now let me check the existing UI components available:
Scanning 56 files
I have all the components I need. Let me read the button, input, card, and label components to understand their APIs:
Now I have all the information I need. Let me create a clean, simple login page using the existing design system components:
The tooltip below is inactive (active=false) — nothing should render:
Dots
Pulse
Spinner
{children}
);
export const DemoDefaultExample = () => (
{children}
);
const markdown =
'Here is a concise answer with **markdown** support:\n\n```ts\nexport type ChatStatus = "ready" | "streaming";\n```\n\nThe UI stays presentation-only — your SDK owns the message array.';
export const DemoWithMarkdownExample = () => (
{children}
);
export const DemoLoadingExample = () => (
Official React documentation for learning modern React patterns.
Selected:{" "} {value.join(", ") || "None"}
{feature.badge ? (
{feature.badge}
) : null}
Choose a subscription
Pick a plan. Try a month on us!
*APY is variable and subject to change at our discretion, without prior notice.
Compare plans
{addOns.map((addon) => (
))}
{addon.title}
{addon.description}
Status: {isSelected ? "Enabled" : "Disabled"}
Primary variant
Secondary variant
{sizes.map((size, index) => (
{index < sizes.length - 1 &&
))}
);
}
```
### With Icons
```tsx
import { Chip } from "@thenamespace/uikit";
import {
ArrowDown01Icon,
CheckmarkCircle02Icon,
CircleIcon,
Clock01Icon,
Cancel01Icon,
HugeiconsIcon,
} from "@thenamespace/uikit/icons";
export function ChipWithIcon() {
return (
{size}
{/* Color labels header */}
{colors.map((color) => (
{color}
))}
{variants.map((variant) => (
Label
))}
))}
{variant}
{colors.map((color) => (
Current color:{" "} {color ? color.toString("hex") : "(empty)"}
{/* Controls */}
{/* Color Value Display */}
);
}
```
### Disabled
```tsx
import {ColorArea} from "@thenamespace/uikit";
export function ColorAreaDisabled() {
return (
{/* Color Space Select */}
{/* X Channel Select */}
{/* Y Channel Select */}
{/* Color Area */}
{color.toString(colorSpace)}
Edit individual HSL channels:
Selected: {color.toString("hex")}
{colorChannelsByColorSpace[colorSpace].map((channel) => (
))}
{colorChannelsByColorSpace[colorSpace].map((channel: ColorChannel) => (
// @ts-expect-error - TypeScript can't correlate dynamic colorSpace with channel type
))}
Current color: {color.toString("hsl")}
Current color: {color.toString("hsl")}
Current color: {color.toString("rgb")}
Circle (default)
{colors.map((color) => (
))}
Square
{colors.map((color) => (
))}
{sizes.map((size) => (
);
}
```
### Stack Layout
```tsx
import {ColorSwatchPicker} from "@thenamespace/uikit";
const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];
export function StackLayout() {
return (
{size}
{colors.map((color) => (
))}
))}
Selected: {value.toString("hex")}
{/* Glow effect */}
);
}
```
### Accessibility
Use `colorName` to provide a custom accessible name for the color, and `aria-label` to add context about how the color is used.
```tsx
import {ColorSwatch} from "@thenamespace/uikit";
export function ColorSwatchAccessibility() {
return (
Glow Effect
{/* Gradient swatch */}
{colors.map((color) => (
({
boxShadow: `0 0 20px 2px ${color}`,
})}
/>
))}
Gradient
{colors.map((color) => (
({
background: `linear-gradient(135deg, ${c.toString("css")}, white)`,
})}
/>
))}
Selected: {selectedAnimal?.name || "None"}
Input value: {inputValue || "(empty)"}
Focus (default)
Input
Manual
{x}
UI component
{["Projects", "Tasks", "People", "Documents", "Channels"].map((x) => (
{x}
))}
{(["sm", "md", "lg"] as const).map((value) => (
))}
);
}
export const DemoSizesExample = () =>
{(["transparent", "opaque", "blur"] as const).map((value) => (
))}
);
}
export const DemoBackdropVariantsExample = () => `.
### Command.InputGroup
The search field container wrapping prefix, input, and suffix elements.
| Prop | Type | Default | Description |
| ----------- | --------- | ------- | ---------------------------------------------------- |
| `autoFocus` | `boolean` | `true` | Whether the input is focused when the palette opens. |
Also supports all RAC [SearchField](https://react-spectrum.adobe.com/react-aria/SearchField.html) props.
### Command.InputGroup.Prefix
Leading content inside the input group (e.g., a search icon). Renders a plain `
`.
### Command.InputGroup.Input
The text input element for searching commands.
| Prop | Type | Default | Description |
| ------------- | -------- | ---------------------- | ----------------- |
| `placeholder` | `string` | `"Search commands..."` | Placeholder text. |
Also supports all RAC [Input](https://react-spectrum.adobe.com/react-aria/TextField.html) props.
### Command.InputGroup.Suffix
Trailing content inside the input group. Renders a plain `
`.
### Command.InputGroup.ClearButton
A close button that clears the search input. Automatically hidden when the input is empty.
Also supports all [Namespace UIKit CloseButton](https://namespace.com/docs/react/components/close-button) props.
### Command.List
The scrollable list of command items. Backed by RAC `Menu`.
| Prop | Type | Default | Description |
| ------------------ | ----------------- | ------- | ----------------------------------------------- |
| `renderEmptyState` | `() => ReactNode` | — | Custom empty state content when no items match. |
Also supports all RAC [Menu](https://react-spectrum.adobe.com/react-aria/Menu.html) props.
### Command.Item
An individual command entry. Supports icons, labels, and keyboard shortcuts.
Also supports all RAC [MenuItem](https://react-spectrum.adobe.com/react-aria/Menu.html#menuitem) props.
### Command.Group
Groups related command items under a heading.
| Prop | Type | Default | Description |
| --------- | ----------- | ------- | ---------------------------- |
| `heading` | `ReactNode` | — | Heading label for the group. |
Also supports all RAC [MenuSection](https://react-spectrum.adobe.com/react-aria/Menu.html#menusection) props.
### Command.Separator
A horizontal divider between groups.
Also supports all RAC [Separator](https://react-spectrum.adobe.com/react-aria/Separator.html) props.
### Command.Footer
Content area below the list (e.g., keyboard shortcut hints). Renders a plain `
`.
# Composed Chart
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/composed-chart
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/composed-chart.mdx
> A composed chart that combines Bar, Line, and Area series in a single cartesian chart for multi-metric dashboards.
## Usage
{/* DEMO composed-chart-default */}
```tsx
"use client";
import { ComposedChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
import { ChartTooltip } from "@thenamespace/uikit/chart-tooltip";
function Legend({
items,
}: {
items: ReadonlyArray<{ color: string; label: string }>;
}) {
return (
Revenue & Orders
`${(value / 1000).toFixed(0)}k`}
width={40}
yAxisId="left"
/>
!active || !payload?.length ? null : (
{label}
{payload.map((entry) => (
{entry.name}
{entry.dataKey === "revenue"
? `${Number(entry.value).toLocaleString()}`
: Number(entry.value).toLocaleString()}
))}
)
}
/>
);
```
## Anatomy
Import the ComposedChart component and access all parts using dot notation.
```tsx
import { ComposedChart } from "@thenamespace/uikit";
;
```
## Stacked Bar With Line
{/* DEMO composed-chart-stacked-bar-with-line */}
```tsx
"use client";
import { ComposedChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
function Legend({
items,
}: {
items: ReadonlyArray<{ color: string; label: string }>;
}) {
return (
AI Share of Committed Code
value >= 1000 ? `${(value / 1000).toFixed(0)}K` : `${value}`
}
width={35}
yAxisId="left"
/>
`${value}%`}
width={40}
yAxisId="right"
/>
{bars.map((bar, index) => (
);
};
```
## Area With Line
{/* DEMO composed-chart-area-with-line */}
```tsx
"use client";
import { ComposedChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
function Legend({
items,
}: {
items: ReadonlyArray<{ color: string; label: string }>;
}) {
return (
value >= 1000 ? `${(value / 1000).toFixed(0)}k` : `${value}`
}
width={dual ? 35 : 30}
{...(dual ? { yAxisId: "left" } : {})}
/>
{dual ? (
`${value}%`}
width={35}
yAxisId="right"
/>
) : null}
);
}
const defaultData = [
{ month: "Jan", orders: 320, revenue: 4200 },
{ month: "Feb", orders: 450, revenue: 5800 },
{ month: "Mar", orders: 380, revenue: 4900 },
{ month: "Apr", orders: 520, revenue: 7200 },
{ month: "May", orders: 480, revenue: 6100 },
{ month: "Jun", orders: 600, revenue: 8400 },
{ month: "Jul", orders: 550, revenue: 7800 },
{ month: "Aug", orders: 680, revenue: 9200 },
{ month: "Sep", orders: 620, revenue: 8600 },
{ month: "Oct", orders: 750, revenue: 10200 },
{ month: "Nov", orders: 700, revenue: 9800 },
{ month: "Dec", orders: 820, revenue: 11500 },
];
const sessions = defaultData.map((item, index) => ({
month: item.month,
sessions: [
12000, 18000, 15000, 22000, 19000, 25000, 23000, 28000, 26000, 31000, 29000,
34000,
][index]!,
target: [
15000, 16000, 17000, 18000, 19000, 20000, 21000, 22000, 23000, 24000, 25000,
26000,
][index]!,
}));
export const DemoAreaWithLineExample = () => (
Sessions vs Target
);
```
## Bar With Area
{/* DEMO composed-chart-bar-with-area */}
```tsx
"use client";
import { ComposedChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
function Legend({
items,
}: {
items: ReadonlyArray<{ color: string; label: string }>;
}) {
return (
Impressions & CTR
value >= 1000 ? `${(value / 1000).toFixed(0)}k` : `${value}`
}
width={35}
yAxisId="left"
/>
`${value}%`}
width={35}
yAxisId="right"
/>
);
```
## Multi Type
{/* DEMO composed-chart-multi-type */}
```tsx
"use client";
import { ComposedChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
function Legend({
items,
}: {
items: ReadonlyArray<{ color: string; label: string }>;
}) {
return (
value >= 1000 ? `${(value / 1000).toFixed(0)}k` : `${value}`
}
width={dual ? 35 : 30}
{...(dual ? { yAxisId: "left" } : {})}
/>
{dual ? (
`${value}%`}
width={35}
yAxisId="right"
/>
) : null}
);
}
const defaultData = [
{ month: "Jan", orders: 320, revenue: 4200 },
{ month: "Feb", orders: 450, revenue: 5800 },
{ month: "Mar", orders: 380, revenue: 4900 },
{ month: "Apr", orders: 520, revenue: 7200 },
{ month: "May", orders: 480, revenue: 6100 },
{ month: "Jun", orders: 600, revenue: 8400 },
{ month: "Jul", orders: 550, revenue: 7800 },
{ month: "Aug", orders: 680, revenue: 9200 },
{ month: "Sep", orders: 620, revenue: 8600 },
{ month: "Oct", orders: 750, revenue: 10200 },
{ month: "Nov", orders: 700, revenue: 9800 },
{ month: "Dec", orders: 820, revenue: 11500 },
];
const analytics = defaultData.map((item, index) => ({
bounceRate: [42, 38, 40, 35, 37, 32, 34, 30, 31, 28, 29, 26][index]!,
month: item.month,
pageViews: [
8200, 11500, 9800, 14200, 12100, 16800, 15200, 18400, 17200, 20500, 19600,
23000,
][index]!,
users: [
3200, 4500, 3800, 5600, 4800, 6600, 6000, 7200, 6800, 8100, 7700, 9100,
][index]!,
}));
export const DemoMultiTypeExample = () => (
Site Analytics
);
```
## CSS Classes
### Element Classes
- `.composed-chart` — Root container wrapping `ResponsiveContainer` and the Recharts chart.
### Recharts Theming
The following CSS rules target Recharts internal class names to apply Namespace UIKit design tokens automatically:
- `.composed-chart .recharts-cartesian-axis-tick-value` — Axis tick labels. 10px muted text.
- `.composed-chart .recharts-cartesian-axis-line` — Axis lines. Hidden by default.
- `.composed-chart .recharts-cartesian-axis-tick-line` — Tick lines. Hidden by default.
- `.composed-chart .recharts-cartesian-grid line` — Cartesian grid lines. Muted stroke at 0.15 opacity.
- `.composed-chart .recharts-tooltip-cursor` — Tooltip cursor. Dashed vertical line on hover.
- `.composed-chart .recharts-active-dot circle` — Active dot. Outlined with surface color for contrast.
## API Reference
### ComposedChart
The root wrapper. Renders a `ResponsiveContainer` + Recharts `ComposedChart` with Namespace UIKit CSS theming applied automatically.
| Prop | Type | Default | Description |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `data` | `Record[]` | — | Chart data — array of objects with numeric/string fields for each series. |
| `height` | `number` | `300` | Chart height in pixels. |
| `width` | ``number \| `${number}%` `` | `"100%"` | Chart width in pixels or percentage string. |
| `margin` | `{ top?: number; right?: number; bottom?: number; left?: number }` | `{ top: 8, right: 8, bottom: 0, left: 0 }` | Recharts margin around the chart area. |
| `children` | `ReactNode` | — | Recharts child components (`ComposedChart.Bar`, `ComposedChart.Line`, `ComposedChart.Area`, etc.). |
Also supports all native `div` HTML attributes.
### ComposedChart.Bar
Re-exported Recharts `Bar` component. Follows the [Recharts Bar API](https://recharts.github.io/en-US/api/Bar/).
### ComposedChart.Line
Re-exported Recharts `Line` component. Follows the [Recharts Line API](https://recharts.github.io/en-US/api/Line/).
### ComposedChart.Area
Re-exported Recharts `Area` component. Follows the [Recharts Area API](https://recharts.github.io/en-US/api/Area/).
### ComposedChart.XAxis
Re-exported Recharts `XAxis` component. Follows the [Recharts XAxis API](https://recharts.github.io/en-US/api/XAxis/).
### ComposedChart.YAxis
Re-exported Recharts `YAxis` component. Follows the [Recharts YAxis API](https://recharts.github.io/en-US/api/YAxis/).
### ComposedChart.Grid
Re-exported Recharts `CartesianGrid` component. Follows the [Recharts CartesianGrid API](https://recharts.github.io/en-US/api/CartesianGrid/).
### ComposedChart.Tooltip
Re-exported Recharts `Tooltip` component. Follows the [Recharts Tooltip API](https://recharts.github.io/en-US/api/Tooltip/). Use with `ComposedChart.TooltipContent` for styled tooltips.
### ComposedChart.TooltipContent
Pre-built tooltip renderer for Recharts. Pass as the `content` prop of `ComposedChart.Tooltip`. See [ChartTooltip](/react/components/chart-tooltip) for full props.
# Context Menu
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/context-menu
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/context-menu.mdx
> A right-click context menu with nested submenus, selection state, and long-press support for touch.
## Usage
{/* DEMO context-menu-default */}
```tsx
"use client";
import { Kbd } from "@thenamespace/uikit";
import { ContextMenu } from "@thenamespace/uikit";
const Trigger = ({ children = "Right-click here" }: { children?: string }) => (
);
const Item = ({
disabled = false,
label,
shortcut,
}: {
disabled?: boolean;
label: string;
shortcut?: string;
}) => (
{label}
{shortcut ? (
{shortcut}
) : null}
);
function DefaultDemo() {
return (
);
}
export const DemoDefaultExample = () =>
;
```
## Controlled
{/* DEMO context-menu-controlled */}
```tsx
"use client";
import { useState } from "react";
import { Kbd } from "@thenamespace/uikit";
import { ContextMenu } from "@thenamespace/uikit";
const Trigger = ({ children = "Right-click here" }: { children?: string }) => (
);
const Item = ({
disabled = false,
label,
shortcut,
}: {
disabled?: boolean;
label: string;
shortcut?: string;
}) => (
{label}
{shortcut ? (
{shortcut}
) : null}
);
function ControlledDemo() {
const [open, setOpen] = useState(false);
return (
{[1, 2, 3].map((x) => (
);
}
export const DemoControlledExample = () =>
);
const Item = ({
disabled = false,
label,
shortcut,
}: {
disabled?: boolean;
label: string;
shortcut?: string;
}) => (
{label}
{shortcut ? (
{shortcut}
) : null}
);
export const DemoDisabledExample = () => (
);
```
## Long Press
{/* DEMO context-menu-long-press */}
```tsx
"use client";
import { Kbd } from "@thenamespace/uikit";
import { ContextMenu } from "@thenamespace/uikit";
const Trigger = ({ children = "Right-click here" }: { children?: string }) => (
);
const Item = ({
disabled = false,
label,
shortcut,
}: {
disabled?: boolean;
label: string;
shortcut?: string;
}) => (
{label}
{shortcut ? (
{shortcut}
) : null}
);
export const DemoLongPressExample = () => (
);
```
## With Sections
{/* DEMO context-menu-with-sections */}
```tsx
"use client";
import { Header, Kbd } from "@thenamespace/uikit";
import { ContextMenu } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
const Trigger = ({ children = "Right-click here" }: { children?: string }) => (
);
const Item = ({
disabled = false,
label,
shortcut,
}: {
disabled?: boolean;
label: string;
shortcut?: string;
}) => (
{label}
{shortcut ? (
{shortcut}
) : null}
);
function Sections() {
return (
Edit
{[
["Cut", "lucide:scissors", "⌘ X"],
["Copy", "lucide:copy", "⌘ C"],
["Paste", "lucide:clipboard", "⌘ V"],
].map(([label, icon, key]) => (
))}
Manage
{[
["Rename", "lucide:pencil"],
["Copy Link", "lucide:link"],
["Delete", "lucide:trash-2"],
].map(([label, icon]) => (
))}
);
}
export const DemoWithSectionsExample = () =>
);
const Item = ({
disabled = false,
label,
shortcut,
}: {
disabled?: boolean;
label: string;
shortcut?: string;
}) => (
{label}
{shortcut ? (
{shortcut}
) : null}
);
function Selection() {
const [selected, setSelected] = useState(new Set(["grid"]));
return (
View
{["grid", "list", "columns"].map((view) => (
))}
);
}
export const DemoWithSelectionExample = () =>
);
const Item = ({
disabled = false,
label,
shortcut,
}: {
disabled?: boolean;
label: string;
shortcut?: string;
}) => (
{label}
{shortcut ? (
{shortcut}
) : null}
);
function Submenus() {
const [bookmarks, setBookmarks] = useState(new Set(["bookmarks"]));
const [person, setPerson] = useState(new Set(["junior"]));
return (
More Tools
People
{["junior", "andres", "volodymyr", "diego"].map((name) => (
))}
);
}
export const DemoWithSubmenusExample = () =>
{items.map(({ color, label }) => (
);
}
const defaultData = [
{ month: "Jan", orders: 320, revenue: 4200 },
{ month: "Feb", orders: 450, revenue: 5800 },
{ month: "Mar", orders: 380, revenue: 4900 },
{ month: "Apr", orders: 520, revenue: 7200 },
{ month: "May", orders: 480, revenue: 6100 },
{ month: "Jun", orders: 600, revenue: 8400 },
{ month: "Jul", orders: 550, revenue: 7800 },
{ month: "Aug", orders: 680, revenue: 9200 },
{ month: "Sep", orders: 620, revenue: 8600 },
{ month: "Oct", orders: 750, revenue: 10200 },
{ month: "Nov", orders: 700, revenue: 9800 },
{ month: "Dec", orders: 820, revenue: 11500 },
];
export const DemoDefaultExample = () => (
{label}
))}
{items.map(({ color, label }) => (
);
}
const codeData = [
{
aiPct: 72,
cli: 800,
cloudAgent: 200,
day: "Mar 13",
ide: 2200,
other: 100,
},
{ aiPct: 65, cli: 500, cloudAgent: 100, day: "Mar 14", ide: 1200, other: 80 },
{ aiPct: 78, cli: 400, cloudAgent: 150, day: "Mar 15", ide: 3200, other: 50 },
{
aiPct: 88,
cli: 1200,
cloudAgent: 300,
day: "Mar 16",
ide: 13500,
other: 200,
},
{
aiPct: 85,
cli: 1000,
cloudAgent: 250,
day: "Mar 17",
ide: 13200,
other: 180,
},
{ aiPct: 60, cli: 200, cloudAgent: 50, day: "Mar 18", ide: 800, other: 30 },
{ aiPct: 55, cli: 150, cloudAgent: 40, day: "Mar 19", ide: 600, other: 20 },
{ aiPct: 50, cli: 100, cloudAgent: 30, day: "Mar 22", ide: 400, other: 15 },
{ aiPct: 48, cli: 80, cloudAgent: 20, day: "Mar 25", ide: 300, other: 10 },
{
aiPct: 70,
cli: 600,
cloudAgent: 200,
day: "Mar 28",
ide: 5000,
other: 100,
},
{
aiPct: 75,
cli: 800,
cloudAgent: 250,
day: "Mar 31",
ide: 8500,
other: 150,
},
{ aiPct: 68, cli: 500, cloudAgent: 150, day: "Apr 3", ide: 3000, other: 80 },
{
aiPct: 82,
cli: 900,
cloudAgent: 300,
day: "Apr 6",
ide: 10500,
other: 200,
},
{
aiPct: 90,
cli: 1500,
cloudAgent: 500,
day: "Apr 7",
ide: 23000,
other: 300,
},
{
aiPct: 85,
cli: 1200,
cloudAgent: 400,
day: "Apr 9",
ide: 18000,
other: 250,
},
];
export const DemoStackedBarWithLineExample = () => {
const bars = [
{ color: "var(--chart-4)", key: "ide", label: "IDE" },
{ color: "var(--chart-2)", key: "cli", label: "CLI" },
{ color: "var(--chart-3)", key: "cloudAgent", label: "Cloud Agent" },
{ color: "var(--chart-1)", key: "other", label: "Other" },
] as const;
return (
{label}
))}
{items.map(({ color, label }) => (
);
}
function Axes({ dual = false }: { dual?: boolean }) {
return (
<>
{label}
))}
{items.map(({ color, label }) => (
);
}
const defaultData = [
{ month: "Jan", orders: 320, revenue: 4200 },
{ month: "Feb", orders: 450, revenue: 5800 },
{ month: "Mar", orders: 380, revenue: 4900 },
{ month: "Apr", orders: 520, revenue: 7200 },
{ month: "May", orders: 480, revenue: 6100 },
{ month: "Jun", orders: 600, revenue: 8400 },
{ month: "Jul", orders: 550, revenue: 7800 },
{ month: "Aug", orders: 680, revenue: 9200 },
{ month: "Sep", orders: 620, revenue: 8600 },
{ month: "Oct", orders: 750, revenue: 10200 },
{ month: "Nov", orders: 700, revenue: 9800 },
{ month: "Dec", orders: 820, revenue: 11500 },
];
const impressions = defaultData.map((item, index) => ({
ctr: [3.2, 3.8, 3.5, 4.2, 4, 4.8, 4.5, 5.1, 4.9, 5.5, 5.2, 5.8][index]!,
impressions: [
45000, 52000, 48000, 61000, 58000, 72000, 68000, 78000, 75000, 85000, 82000,
92000,
][index]!,
month: item.month,
}));
export const DemoBarWithAreaExample = () => (
{label}
))}
{items.map(({ color, label }) => (
);
}
function Axes({ dual = false }: { dual?: boolean }) {
return (
<>
{label}
))}
{children}
{children}
Menu is {open ? "open" : "closed"}
{children}
{children}
{children}
{children}
{children}
` by default.
| Prop | Type | Default | Description |
| ----------- | ----------- | ------- | ---------------------------------- |
| `children` | `ReactNode` | — | Content that can be right-clicked. |
| `className` | `string` | — | Additional CSS classes. |
### ContextMenu.Popover
The floating panel positioned at the cursor coordinates.
| Prop | Type | Default | Description |
| ----------- | ----------- | ---------------- | ------------------------------------------- |
| `offset` | `number` | `2` | Distance from the anchor point in pixels. |
| `placement` | `Placement` | `"bottom start"` | Preferred placement relative to the cursor. |
Also supports all RAC [Popover](https://react-spectrum.adobe.com/react-aria/Popover.html) props (except `isOpen`, `triggerRef`, and `children`).
### ContextMenu.Menu
The list of menu items. Automatically closes the context menu when an item is selected.
| Prop | Type | Default | Description |
| --------- | ------------ | ------- | ----------------------------------------------------------- |
| `onClose` | `() => void` | — | Custom close handler. Defaults to closing the context menu. |
Also supports all RAC [Menu](https://react-spectrum.adobe.com/react-aria/Menu.html) props.
### ContextMenu.Item
An individual menu item. Re-exports [Namespace UIKit DropdownItem](https://namespace.com/docs/react/components/dropdown).
Also supports all [Namespace UIKit DropdownItem](https://namespace.com/docs/react/components/dropdown) props.
### ContextMenu.ItemIndicator
Selection indicator for checkbox/radio menu items. Re-exports [Namespace UIKit DropdownItemIndicator](https://namespace.com/docs/react/components/dropdown).
### ContextMenu.Section
Groups related menu items. Re-exports [Namespace UIKit DropdownSection](https://namespace.com/docs/react/components/dropdown).
Also supports all [Namespace UIKit DropdownSection](https://namespace.com/docs/react/components/dropdown) props.
### ContextMenu.SubmenuTrigger
Wraps a menu item that opens a nested submenu on hover. Re-exports [Namespace UIKit DropdownSubmenuTrigger](https://namespace.com/docs/react/components/dropdown).
### ContextMenu.SubmenuIndicator
Chevron icon indicating a submenu. Re-exports [Namespace UIKit DropdownSubmenuIndicator](https://namespace.com/docs/react/components/dropdown).
### ContextMenu.Separator
A horizontal divider between menu groups.
Also supports all RAC [Separator](https://react-spectrum.adobe.com/react-aria/Separator.html) props.
# Data Grid
**Category**: components
**URL**: https://namespace-uikit.vercel.app/docs/components/data-grid
**Source**: https://github.com/thenamespace/uikit/blob/main/apps/docs/content/docs/components/data-grid.mdx
> A full-featured data grid with sorting, selection, column resizing, pinned columns, drag-and-drop row reorder, virtualization, and async loading — built on the Namespace UIKit Table.
## Usage
{/* DEMO data-grid-default */}
```tsx
"use client";
import type { Selection } from "react-aria-components";
import { useState } from "react";
import {
Copy01Icon,
Delete02Icon,
MoreVerticalIcon,
PencilEdit01Icon,
ViewIcon,
} from "@thenamespace/uikit/icons";
import { HugeiconsIcon } from "@thenamespace/uikit/icons";
import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";
import { Button } from "@thenamespace/uikit/button";
import { Chip } from "@thenamespace/uikit/chip";
import { Dropdown } from "@thenamespace/uikit/dropdown";
type Payment = {
amount: number;
customer: string;
date: string;
description: string;
email: string;
fee: number;
id: string;
method: string;
net: number;
region: string;
status: "failed" | "processing" | "refunded" | "succeeded";
};
const payments: Payment[] = [
{
amount: 1999,
customer: "Olivia Martin",
date: "2025-12-01",
description: "Annual subscription — Pro plan",
email: "olivia@example.com",
fee: 59.97,
id: "pay_1N3x7K",
method: "Visa •••• 4242",
net: 1939.03,
region: "North America",
status: "succeeded",
},
{
amount: 39,
customer: "Jackson Lee",
date: "2025-12-02",
description: "Monthly add-on — Extra seats",
email: "jackson@example.com",
fee: 1.43,
id: "pay_1N3x8L",
method: "Mastercard •••• 5555",
net: 37.57,
region: "North America",
status: "processing",
},
{
amount: 299,
customer: "Isabella Nguyen",
date: "2025-12-03",
description: "Quarterly subscription — Team plan",
email: "isabella@example.com",
fee: 8.97,
id: "pay_1N3x9M",
method: "Visa •••• 1234",
net: 290.03,
region: "Asia Pacific",
status: "succeeded",
},
{
amount: 99,
customer: "William Kim",
date: "2025-12-04",
description: "Monthly subscription — Starter plan",
email: "will@example.com",
fee: 3.17,
id: "pay_1N3xAN",
method: "Amex •••• 3782",
net: 95.83,
region: "Asia Pacific",
status: "failed",
},
{
amount: 450,
customer: "Sofia Davis",
date: "2025-12-05",
description: "One-time purchase — Enterprise setup",
email: "sofia@example.com",
fee: 13.5,
id: "pay_1N3xBP",
method: "Visa •••• 9012",
net: 436.5,
region: "Europe",
status: "succeeded",
},
{
amount: 150,
customer: "Liam Johnson",
date: "2025-12-06",
description: "Monthly subscription — Pro plan",
email: "liam@example.com",
fee: 4.5,
id: "pay_1N3xCQ",
method: "Mastercard •••• 6789",
net: 145.5,
region: "Europe",
status: "refunded",
},
{
amount: 2450,
customer: "Emma Wilson",
date: "2025-12-07",
description: "Annual subscription — Enterprise plan",
email: "emma@example.com",
fee: 73.5,
id: "pay_1N3xDR",
method: "Visa •••• 4242",
net: 2376.5,
region: "North America",
status: "succeeded",
},
];
const paymentStatusColor = {
failed: "danger",
processing: "warning",
refunded: "default",
succeeded: "success",
} as const;
const formatCurrency = (value: number) =>
new Intl.NumberFormat("en-US", {
currency: "USD",
style: "currency",
}).format(value);
const formatDate = (value: string) =>
new Date(value).toLocaleDateString("en-US", {
day: "numeric",
month: "short",
year: "numeric",
});
function StoryIcon({ icon }: { icon: typeof MoreVerticalIcon }) {
return
{
if (key === "copy") void navigator.clipboard.writeText(paymentId);
}}
>
);
}
const paymentColumns: DataGridColumn[] = [
{
accessorKey: "customer",
allowsResizing: true,
allowsSorting: true,
cell: (payment) => (
{payment.status}
),
header: "Status",
id: "status",
minWidth: 120,
},
...(
[
["amount", "Amount", "font-medium tabular-nums", 110],
["fee", "Fee", "text-muted tabular-nums", 90],
["net", "Net", "font-medium tabular-nums", 110],
] as const
).map(
([key, header, className, minWidth]): DataGridColumn => ({
accessorKey: key,
align: "end",
allowsResizing: true,
allowsSorting: true,
cell: (payment) => (
{formatCurrency(payment[key])}
),
header,
id: key,
minWidth,
}),
),
{
accessorKey: "method",
allowsResizing: true,
header: "Payment Method",
id: "method",
minWidth: 170,
},
{
accessorKey: "region",
allowsResizing: true,
allowsSorting: true,
header: "Region",
id: "region",
minWidth: 130,
},
{
accessorKey: "description",
allowsResizing: true,
cellClassName: "text-muted",
header: "Description",
id: "description",
minWidth: 240,
},
{
accessorKey: "date",
allowsResizing: true,
allowsSorting: true,
cell: (payment) => (
{formatDate(payment.date)}
),
header: "Date",
id: "date",
minWidth: 120,
},
{
align: "end",
allowsResizing: false,
cell: (payment) => (new Set());
const count = selected === "all" ? payments.length : selected.size;
return (
payment.id}
renderEmptyState={() => "No payments found."}
selectedKeys={selected}
selectionMode="multiple"
variant="primary"
onSelectionChange={setSelected}
/>
{count > 0 ? (
);
};
```
The `DataGrid` component takes a flat `data` array, a `columns` definition, and a `getRowId` function. It renders a fully accessible table with built-in support for sorting, selection, column resizing, and more.
## Anatomy
Import the `DataGrid` component — it is not a compound component and has no `DataGrid.*` sub-parts.
```tsx
import { DataGrid } from "@thenamespace/uikit";
` objects. Each column has an `id`, a `header`, and either an `accessorKey` (to read a value from the row object) or a custom `cell` renderer.
```tsx
import type { DataGridColumn } from "@thenamespace/uikit";
interface Payment {
id: string;
customer: string;
amount: number;
status: "succeeded" | "failed";
}
const columns: DataGridColumn[] = [
{
id: "customer",
header: "Customer",
accessorKey: "customer",
isRowHeader: true,
allowsSorting: true,
},
{
id: "amount",
header: "Amount",
accessorKey: "amount",
align: "end",
cell: (item) => `$${item.amount.toFixed(2)}`,
},
{
id: "status",
header: "Status",
accessorKey: "status",
},
];
```
### Custom Cell Rendering
The `cell` function receives the full row item and column definition. Return any `ReactNode`:
```tsx
{
id: "status",
header: "Status",
cell: (item) => (
{item.status}
),
}
```
### Custom Header Rendering
The `header` property accepts a string, a `ReactNode`, or a render function that receives `{ sortDirection }` for sortable columns:
```tsx
{
id: "amount",
header: ({ sortDirection }) => (
Amount {sortDirection === "ascending" ? "↑" : sortDirection === "descending" ? "↓" : ""}
),
allowsSorting: true,
}
```
## Row Selection
Enable row selection with `selectionMode` and `showSelectionCheckboxes`. Supports both `"single"` and `"multiple"` modes with controlled or uncontrolled state.
```tsx
const [selectedKeys, setSelectedKeys] = useState(new Set());
item.id}
selectionMode="multiple"
showSelectionCheckboxes
selectedKeys={selectedKeys}
onSelectionChange={setSelectedKeys}
/>;
```
## Sorting
Mark columns as sortable with `allowsSorting: true`. In uncontrolled mode, the DataGrid sorts data client-side using locale-aware string comparison (or a custom `sortFn`). For server-side sorting, pass a controlled `sortDescriptor` and handle `onSortChange`.
### Uncontrolled (client-side)
```tsx
item.id}
defaultSortDescriptor={{ column: "customer", direction: "ascending" }}
/>
```
### Controlled (server-side)
```tsx
const [sortDescriptor, setSortDescriptor] = useState({
column: "date",
direction: "descending",
});
item.id}
sortDescriptor={sortDescriptor}
onSortChange={setSortDescriptor}
/>;
```
### Custom Sort Function
Provide a `sortFn` on a column for custom comparison logic:
```tsx
{
id: "priority",
header: "Priority",
allowsSorting: true,
sortFn: (a, b) => priorityOrder[a.priority] - priorityOrder[b.priority],
}
```
## Column Resizing
Enable column resizing with `allowsColumnResize` on the DataGrid and `allowsResizing` on individual columns. Columns must have `minWidth` set.
```tsx
item.id}
allowsColumnResize
onColumnResize={(widths) => console.log("Resizing:", widths)}
onColumnResizeEnd={(widths) => console.log("Final widths:", widths)}
/>
```
## Pinned Columns
Pin columns to the start or end edge so they stay visible during horizontal scroll. Pinned columns must have a numeric `width` or `minWidth`.
```tsx
const columns: DataGridColumn[] = [
{
id: "name",
header: "Company",
pinned: "start",
minWidth: 160,
// ...
},
// ... scrollable columns ...
{
id: "actions",
header: "",
pinned: "end",
width: 50,
cell: (item) => item.id}
onReorder={(event) => setTasks(event.reorderedData)}
/>;
```
For advanced drag-and-drop scenarios (cross-list, custom drag items), pass `dragAndDropHooks` directly from RAC's `useDragAndDrop`.
## Expandable Rows
{/* DEMO data-grid-expandable-rows */}
```tsx
"use client";
import type { Selection } from "react-aria-components";
import { useState } from "react";
import {
File01Icon,
File02Icon,
Folder01Icon,
FolderOpenIcon,
Image01Icon,
} from "@thenamespace/uikit/icons";
import { HugeiconsIcon } from "@thenamespace/uikit/icons";
import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";
import { Chip } from "@thenamespace/uikit/chip";
type TreeRow = {
children?: TreeRow[];
id: string;
kind: "document" | "folder" | "image" | "text";
modified: string;
name: string;
size: string;
};
const tree: TreeRow[] = [
{
children: [
{
children: [
{
id: "3",
kind: "document",
modified: "Jul 10, 2025",
name: "Weekly Report.pdf",
size: "1.2 MB",
},
{
id: "4",
kind: "document",
modified: "Aug 20, 2025",
name: "Budget.xlsx",
size: "48 KB",
},
],
id: "2",
kind: "folder",
modified: "Aug 2, 2025",
name: "Project Alpha",
size: "2 items",
},
{
id: "8",
kind: "text",
modified: "Sep 14, 2025",
name: "Meeting Notes.md",
size: "12 KB",
},
],
id: "1",
kind: "folder",
modified: "Oct 20, 2025",
name: "Documents",
size: "3 items",
},
{
children: [
{
id: "6",
kind: "image",
modified: "Jan 23, 2026",
name: "hero-1.png",
size: "2.4 MB",
},
{
id: "7",
kind: "image",
modified: "Feb 3, 2026",
name: "hero-2.png",
size: "3.1 MB",
},
],
id: "5",
kind: "folder",
modified: "Feb 3, 2026",
name: "Photos",
size: "2 items",
},
{
id: "9",
kind: "text",
modified: "Mar 1, 2026",
name: "readme.txt",
size: "4 KB",
},
];
export const DemoExpandableRowsExample = function Demo() {
const [expanded, setExpanded] = useState(new Set(["1"]));
const isExpanded = (id: string) => expanded === "all" || expanded.has(id);
const typeLabel = {
document: "Document",
folder: "Folder",
image: "Image",
text: "Text",
} as const;
const typeColor = {
document: "accent",
folder: "warning",
image: "success",
text: "default",
} as const;
const fileColumns: DataGridColumn[] = [
{
accessorKey: "name",
cell: (item) => {
const icon =
item.kind === "folder"
? isExpanded(item.id)
? FolderOpenIcon
: Folder01Icon
: item.kind === "image"
? Image01Icon
: item.kind === "document"
? File02Icon
: File01Icon;
return (
{typeLabel[item.kind]}
),
header: "Type",
id: "kind",
minWidth: 120,
},
{
accessorKey: "size",
align: "end",
cellClassName: "text-muted text-sm tabular-nums",
header: "Size",
id: "size",
minWidth: 100,
},
{
accessorKey: "modified",
cellClassName: "text-muted text-sm tabular-nums",
header: "Date Modified",
id: "modified",
minWidth: 160,
},
];
return (
item.children}
getRowId={(item) => item.id}
treeColumn="name"
variant="primary"
onExpandedChange={setExpanded}
/>
);
};
```
Render hierarchical data by providing a `getChildren` function. The DataGrid recursively renders child rows, auto-generates a chevron toggle in the `treeColumn`, and indents each nested level by `treeIndent` pixels.
```tsx
interface FileRow {
id: string;
name: string;
type: "Folder" | "File";
children?: FileRow[];
}
const [expandedKeys, setExpandedKeys] = useState(new Set(["1"]));
item.id}
getChildren={(item) => item.children}
treeColumn="name"
expandedKeys={expandedKeys}
onExpandedChange={setExpandedKeys}
/>;
```
The `treeColumn` prop specifies which column displays the chevron. If omitted, it defaults to the first `isRowHeader` column (or the first column). Use `defaultExpandedKeys` for uncontrolled expansion, or pair `expandedKeys` with `onExpandedChange` for controlled behavior. Set `treeIndent={0}` to disable automatic per-level indentation.
Expandable rows compose with selection, drag-and-drop, sorting, pinned columns, and column resizing.
## Editable Cells
{/* DEMO data-grid-editable-cells */}
```tsx
"use client";
import { useState } from "react";
import {
Cancel01Icon,
PencilEdit01Icon,
Tick02Icon,
} from "@thenamespace/uikit/icons";
import { HugeiconsIcon } from "@thenamespace/uikit/icons";
import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";
import { Button } from "@thenamespace/uikit/button";
import { Chip } from "@thenamespace/uikit/chip";
import { Input } from "@thenamespace/uikit/input";
import { ListBox } from "@thenamespace/uikit/list-box";
import { NumberStepper } from "@thenamespace/uikit/number-stepper";
import { Select } from "@thenamespace/uikit/select";
import { Switch } from "@thenamespace/uikit/switch";
import { TextField } from "@thenamespace/uikit/textfield";
const priorityColor = {
high: "danger",
low: "default",
medium: "warning",
} as const;
type Feature = {
effort: number;
enabled: boolean;
id: string;
priority: "high" | "low" | "medium";
title: string;
};
const features: Feature[] = [
{
effort: 8,
enabled: true,
id: "feat-1",
priority: "high",
title: "Dark mode",
},
{
effort: 3,
enabled: true,
id: "feat-2",
priority: "medium",
title: "CSV export",
},
{
effort: 5,
enabled: false,
id: "feat-3",
priority: "low",
title: "Keyboard shortcuts",
},
{
effort: 13,
enabled: true,
id: "feat-4",
priority: "high",
title: "Two-factor auth",
},
{
effort: 8,
enabled: false,
id: "feat-5",
priority: "medium",
title: "Bulk import",
},
{
effort: 5,
enabled: true,
id: "feat-6",
priority: "high",
title: "Audit log",
},
{
effort: 3,
enabled: false,
id: "feat-7",
priority: "low",
title: "Webhooks",
},
{
effort: 8,
enabled: true,
id: "feat-8",
priority: "medium",
title: "Custom branding",
},
];
const featurePriorities = [
{ id: "high", label: "High" },
{ id: "medium", label: "Medium" },
{ id: "low", label: "Low" },
] as const;
function EditableTitle({
onSave,
value,
}: {
onSave: (value: string) => void;
value: string;
}) {
const [isEditing, setEditing] = useState(false);
const [draft, setDraft] = useState(value);
const save = () => {
if (draft.trim()) onSave(draft.trim());
setEditing(false);
};
const cancel = () => {
setDraft(value);
setEditing(false);
};
return isEditing ? (
{
if (event.key === "Enter") save();
if (event.key === "Escape") cancel();
}}
>
) : (
) =>
setData((current) =>
current.map((feature) =>
feature.id === id ? { ...feature, ...values } : feature,
),
);
const editableColumns: DataGridColumn[] = [
{
cell: (feature) => (
update(feature.id, { title })}
/>
),
header: "Feature",
id: "title",
isRowHeader: true,
minWidth: 260,
},
{
accessorKey: "priority",
cell: (feature) => (
),
header: "Priority",
id: "priority",
minWidth: 150,
},
{
accessorKey: "effort",
align: "center",
cell: (feature) => (
update(feature.id, { effort })}
>
),
header: "Story Points",
id: "effort",
minWidth: 120,
},
{
accessorKey: "enabled",
align: "center",
cell: (feature) => (
update(feature.id, { enabled })}
>
),
header: "Enabled",
id: "enabled",
minWidth: 100,
},
];
const enabled = data.filter((feature) => feature.enabled).length;
const effort = data.reduce((total, feature) => total + feature.effort, 0);
return (
feature.id}
/>
);
};
```
Use the `cell` render function to embed any interactive component — text fields, selects, switches, number steppers, etc.
## Empty State
{/* DEMO data-grid-empty-state */}
```tsx
"use client";
import {
Add01Icon,
FolderOpenIcon,
MoreVerticalIcon,
} from "@thenamespace/uikit/icons";
import { HugeiconsIcon } from "@thenamespace/uikit/icons";
import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";
import { Button } from "@thenamespace/uikit/button";
import { EmptyState as EmptyStateComponent } from "@thenamespace/uikit/empty-state";
function StoryIcon({ icon }: { icon: typeof MoreVerticalIcon }) {
return [] = [
{
accessorKey: "name",
cellClassName: "font-medium",
header: "Project",
id: "name",
isRowHeader: true,
},
{ accessorKey: "owner", header: "Owner", id: "owner" },
{
accessorKey: "files",
align: "center",
header: "Files",
id: "files",
},
{
accessorKey: "updatedAt",
header: "Last Updated",
id: "updatedAt",
},
];
export const DemoEmptyStateExample = () => (
project.id}
renderEmptyState={() => (
No Projects Yet
Get started by creating your first project. You can always
import existing projects later.
)}
/>
);
```
Provide a `renderEmptyState` function to display a custom empty state when `data` is empty.
```tsx
item.id}
renderEmptyState={() => (
No Projects Yet
Get started by creating your first project.
)}
/>
```
## Async Loading
{/* DEMO data-grid-async-loading */}
```tsx
"use client";
import { useState } from "react";
import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";
import { Chip } from "@thenamespace/uikit/chip";
import { Spinner } from "@thenamespace/uikit/spinner";
const formatDate = (value: string) =>
new Date(value).toLocaleDateString("en-US", {
day: "numeric",
month: "short",
year: "numeric",
});
type Invoice = {
amount: number;
client: string;
id: string;
issuedAt: string;
status: "overdue" | "paid" | "pending";
};
const invoiceClients = [
"Acme Corp",
"Globex Inc",
"Initech",
"Umbrella LLC",
"Stark Industries",
"Wayne Enterprises",
"Hooli",
"Pied Piper",
"Soylent Corp",
"Massive Dynamic",
"Cyberdyne Systems",
"Tyrell Corp",
"Oscorp",
"LexCorp",
"Wonka Industries",
] as const;
const invoiceStatuses = ["paid", "pending", "overdue"] as const;
const seeded = (seed: number) => {
const value = Math.sin(seed) * 10_000;
return value - Math.floor(value);
};
const generateInvoices = (page: number, count: number): Invoice[] => {
const start = page * count;
return Array.from({ length: count }, (_, index) => {
const seed = start + index;
const random = (offset: number) => seeded(seed * 7 + offset);
const month = (seed % 12) + 1;
const day = Math.floor(random(3) * 28) + 1;
return {
amount: Math.round(200 + random(2) * 9800),
client: invoiceClients[Math.floor(random(1) * invoiceClients.length)]!,
id: `INV-${String(1000 + seed)}`,
issuedAt: `2025-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`,
status: invoiceStatuses[Math.floor(random(4) * invoiceStatuses.length)]!,
};
});
};
const invoiceStatusColor = {
overdue: "danger",
paid: "success",
pending: "warning",
} as const;
const invoiceColumns: DataGridColumn[] = [
{
accessorKey: "id",
cellClassName: "font-medium font-mono text-xs",
header: "Invoice",
id: "id",
isRowHeader: true,
},
{ accessorKey: "client", header: "Client", id: "client" },
{
accessorKey: "amount",
align: "end",
cell: (invoice) => (
{new Intl.NumberFormat("en-US", {
currency: "USD",
maximumFractionDigits: 0,
style: "currency",
}).format(invoice.amount)}
),
header: "Amount",
id: "amount",
},
{
accessorKey: "status",
cell: (invoice) => (
{invoice.status}
),
header: "Status",
id: "status",
},
{
accessorKey: "issuedAt",
cell: (invoice) => (
{formatDate(invoice.issuedAt)}
),
header: "Issued",
id: "issuedAt",
},
];
const invoicePageSize = 8;
const invoiceTotal = 50;
export const DemoAsyncLoadingExample = function Demo() {
const [data, setData] = useState(() => generateInvoices(0, invoicePageSize));
const [isLoading, setLoading] = useState(false);
const hasMore = data.length < invoiceTotal;
return (
{data.length} / {invoiceTotal}
) : null}
invoice.id}
isLoadingMore={isLoading}
loadMoreContent={
);
};
```
Use `onLoadMore`, `isLoadingMore`, and `loadMoreContent` to implement infinite scroll loading. The DataGrid renders a sentinel row that triggers `onLoadMore` when it scrolls into view.
```tsx
item.id}
scrollContainerClassName="max-h-[400px] overflow-y-auto"
onLoadMore={hasMore ? handleLoadMore : undefined}
isLoadingMore={isLoading}
loadMoreContent={ item.id}
contentClassName="h-[400px] min-w-[900px] overflow-auto"
rowHeight={58}
headingHeight={37}
/>
```
## Bulk Actions
{/* DEMO data-grid-bulk-actions */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import type { Selection } from "react-aria-components";
import { useState } from "react";
import {
Archive02Icon,
Cancel01Icon,
Delete02Icon,
Download04Icon,
MoreVerticalIcon,
PencilEdit01Icon,
} from "@thenamespace/uikit/icons";
import { HugeiconsIcon } from "@thenamespace/uikit/icons";
import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";
import { ActionBar } from "@thenamespace/uikit/action-bar";
import { Avatar } from "@thenamespace/uikit/avatar";
import { Button } from "@thenamespace/uikit/button";
import { Chip } from "@thenamespace/uikit/chip";
import { Separator } from "@thenamespace/uikit/separator";
const formatDate = (value: string) =>
new Date(value).toLocaleDateString("en-US", {
day: "numeric",
month: "short",
year: "numeric",
});
function StoryIcon({ icon }: { icon: typeof MoreVerticalIcon }) {
return [] = [
{
accessorKey: "name",
allowsSorting: true,
cell: (employee) => (
{employee.name
.split(" ")
.map((part) => part[0])
.join("")}
),
header: "Employee",
id: "name",
isRowHeader: true,
minWidth: 240,
},
{
accessorKey: "department",
allowsSorting: true,
header: "Department",
id: "department",
},
{
accessorKey: "status",
allowsSorting: true,
cell: (employee) => (
{employee.status}
),
header: "Status",
id: "status",
},
{
accessorKey: "joinDate",
allowsSorting: true,
cell: (employee) => (
{formatDate(employee.joinDate)}
),
header: "Joined",
id: "joinDate",
},
];
export const DemoBulkActionsExample = function Demo() {
const [data, setData] = useState(bulkEmployees);
const [selected, setSelected] = useState(new Set());
const count = selected === "all" ? data.length : selected.size;
const selectedIds =
selected === "all" ? new Set(data.map((item) => item.id)) : selected;
return (
<>
employee.id}
selectedKeys={selected}
selectionMode="multiple"
onSelectionChange={setSelected}
/>
0}>
{count}
);
};
```
Combine row selection with an `ActionBar` to provide bulk operations like export, archive, or delete.
## Users
A minimal user directory using the `"secondary"` variant with `accessorKey`-only columns and a row action link — no selection, no sorting.
## Team Members
A full-featured HR table with controlled sorting, multi-selection, pinned columns, column resizing, column visibility toggling, search, filters, and client-side pagination.
## Servers
A server monitoring dashboard with controlled sorting, selection, column visibility toggling, search, status filtering, and rich cell renderers including sparkline charts and circular progress indicators.
### Complex
{/* DEMO data-grid-complex */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import type { Selection, SortDescriptor } from "react-aria-components";
import { useMemo, useState } from "react";
import {
Add01Icon,
Calendar03Icon,
Cancel01Icon,
Copy01Icon,
FilterIcon,
MoreVerticalIcon,
LayoutThreeColumnIcon,
SlidersHorizontalIcon,
} from "@thenamespace/uikit/icons";
import { HugeiconsIcon } from "@thenamespace/uikit/icons";
import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";
import { Avatar } from "@thenamespace/uikit/avatar";
import { Button } from "@thenamespace/uikit/button";
import { Chip } from "@thenamespace/uikit/chip";
import { Dropdown } from "@thenamespace/uikit/dropdown";
import { Input } from "@thenamespace/uikit/input";
import { Link } from "@thenamespace/uikit/link";
import { ListBox } from "@thenamespace/uikit/list-box";
import { Pagination } from "@thenamespace/uikit/pagination";
import { SearchField } from "@thenamespace/uikit/search-field";
import { Select } from "@thenamespace/uikit/select";
import { Separator } from "@thenamespace/uikit/separator";
import { Tooltip } from "@thenamespace/uikit/tooltip";
function StoryIcon({ icon }: { icon: typeof MoreVerticalIcon }) {
return
View
Edit
Delete
);
}
type Country = { code: string; name: string };
type Worker = {
avatar: string;
country: Country;
email: string;
externalWorkerId: string;
id: number;
name: string;
role: string;
startDate: string;
status: "Active" | "Inactive" | "Vacation";
teams: string[];
workerId: string;
workerType: "Contractor" | "Employee";
};
const workerNames = [
"Alice Johnson",
"Bob Smith",
"Charlie Brown",
"David Wilson",
"Eve Martinez",
"Frank Thompson",
"Grace Garcia",
"Hannah Lee",
"Isaac Anderson",
"Julia Roberts",
"Liam Williams",
"Mia White",
"Noah Harris",
"Olivia Martin",
"Peyton Jones",
"Quinn Taylor",
"Ryan Moore",
"Sophia Davis",
"Marcus Lopez",
"Uma Thomas",
"Victoria Jackson",
"William Green",
"Xavier Hill",
"Yara Scott",
"Zoe Baker",
"Aaron Carter",
"Bella Brown",
"Carter Black",
"Daisy Clark",
"Ethan Hunt",
"Fiona Apple",
"George King",
"Harper Knight",
"Ivy Lane",
"Jack Frost",
"Kylie Reed",
"Lucas Grant",
"Molly Shaw",
"Nathan Ford",
"Oliver Stone",
"Penelope Cruz",
"Quentin Cook",
"Ruby Fox",
"Sarah Miles",
"Travis Shaw",
"Ursula Major",
"Vera Mindy",
"Wesley Snipes",
"Xena Warrior",
"Yvette Fielding",
] as const;
const workerRoles = [
"Software Engineer",
"Marketing Specialist",
"HR Manager",
"Data Analyst",
"Project Manager",
"Sales Executive",
"Graphic Designer",
"Operations Coordinator",
"Product Manager",
"Customer Service Representative",
"Network Administrator",
"QA Tester",
"Business Analyst",
"Content Writer",
"UX/UI Designer",
"Accountant",
"Supply Chain Analyst",
"Social Media Manager",
"Web Developer",
"Technical Support Specialist",
"Logistics Manager",
"Environmental Scientist",
] as const;
const countries: Country[] = [
{ code: "ar", name: "Argentina" },
{ code: "au", name: "Australia" },
{ code: "br", name: "Brazil" },
{ code: "ca", name: "Canada" },
{ code: "cn", name: "China" },
{ code: "fr", name: "France" },
{ code: "de", name: "Germany" },
{ code: "jp", name: "Japan" },
{ code: "pt", name: "Portugal" },
{ code: "us", name: "United States" },
{ code: "gb", name: "United Kingdom" },
{ code: "in", name: "India" },
{ code: "mx", name: "Mexico" },
{ code: "kr", name: "South Korea" },
{ code: "es", name: "Spain" },
];
const teamNames = [
"Product",
"Engineering",
"Design",
"Marketing",
"Sales",
"Support",
"Management",
"Other",
] as const;
const workerStatuses = ["Active", "Inactive", "Vacation"] as const;
const workerTypes = ["Employee", "Contractor"] as const;
const workerSeeded = (seed: number) => {
const value = Math.sin(seed) * 10_000;
return value - Math.floor(value);
};
const randomDate = (seed: number) => {
const start = new Date(2025, 0, 1).getTime();
const range = 500 * 24 * 60 * 60 * 1000;
return new Date(start + workerSeeded(seed) * range)
.toISOString()
.split("T")[0]!;
};
const randomTeams = (seed: number) => {
const count = Math.floor(workerSeeded(seed) * 5) + 1;
return [...teamNames]
.toSorted(() => workerSeeded(seed + 99) - 0.5)
.slice(0, count);
};
const workerId = (seed: number) =>
`WRK-${Math.floor(workerSeeded(seed) * 9_000_000) + 1_000_000}`;
const externalId = (seed: number) => {
const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
let value = "EXT-";
for (let index = 0; index < 8; index++)
value +=
alphabet[Math.floor(workerSeeded(seed + index * 3) * alphabet.length)];
return value;
};
const workers: Worker[] = Array.from({ length: 100 }, (_, index) => {
const random = (offset: number) => workerSeeded(index * 7 + offset);
const name = workerNames[Math.floor(random(1) * workerNames.length)]!;
const statusIndex =
(index * 3 + Math.floor(random(5) * 7)) % workerStatuses.length;
return {
avatar: `/assets/generated/avatar-${(index % 26) + 1}.jpg`,
country: countries[Math.floor(random(3) * countries.length)]!,
email: `${name.toLowerCase().replace(/\s+/g, ".")}@example.com`,
externalWorkerId: externalId(index * 17 + 5),
id: index + 1,
name,
role: workerRoles[Math.floor(random(2) * workerRoles.length)]!,
startDate: randomDate(index * 13 + 7),
status: workerStatuses[statusIndex]!,
teams: randomTeams(index * 11 + 3),
workerId: workerId(index * 13 + 1),
workerType: workerTypes[Math.floor(random(4) * workerTypes.length)]!,
};
});
const workerColumnIds = [
"workerId",
"externalWorkerId",
"name",
"country",
"role",
"workerType",
"status",
"startDate",
"teams",
"actions",
] as const;
const workerStatusColor = {
Active: "success",
Inactive: "danger",
Vacation: "warning",
} as const;
function CopyValue({ children }: { children: string }) {
return (
Copy
{children}
);
}
function CountryCell({ country }: { country: Country }) {
return (
{country.name}
);
}
function TeamChips({ teams }: { teams: string[] }) {
return (
{teams.slice(0, 3).map((team) => (
{team}
))}
{teams.length > 3 ? (
+{teams.length - 3}
) : null}
);
}
export const DemoComplexExample = function Demo() {
const [query, setQuery] = useState("");
const [page, setPage] = useState(1);
const [pageSize, setPageSize] = useState(10);
const [selected, setSelected] = useState(new Set());
const [sort, setSort] = useState({
column: "name",
direction: "ascending",
});
const [status, setStatus] = useState("all");
const [type, setType] = useState("all");
const [visibleColumns, setVisibleColumns] = useState(
new Set(workerColumnIds),
);
const filtered = useMemo(() => {
let result = workers;
if (query) {
const normalized = query.toLowerCase();
result = result.filter((worker) =>
[
worker.name,
worker.email,
worker.workerId,
worker.externalWorkerId,
].some((value) => value.toLowerCase().includes(normalized)),
);
}
if (status !== "all")
result = result.filter(
(worker) => worker.status.toLowerCase() === status,
);
if (type !== "all")
result = result.filter(
(worker) => worker.workerType.toLowerCase() === type,
);
return result;
}, [query, status, type]);
const sorted = useMemo(
() =>
filtered.toSorted((left, right) => {
const key = sort.column as keyof Worker;
const leftValue =
key === "country"
? left.country.name
: key === "teams"
? left.teams.join(", ")
: String(left[key] ?? "");
const rightValue =
key === "country"
? right.country.name
: key === "teams"
? right.teams.join(", ")
: String(right[key] ?? "");
const comparison = leftValue.localeCompare(rightValue);
return sort.direction === "descending" ? -comparison : comparison;
}),
[filtered, sort],
);
const pageCount = Math.ceil(sorted.length / pageSize) || 1;
const currentPage = Math.min(page, pageCount);
const paginationPages: (number | "ellipsis")[] =
pageCount <= 5
? Array.from({ length: pageCount }, (_, index) => index + 1)
: [1, 2, "ellipsis", pageCount];
const pageData = sorted.slice(
(currentPage - 1) * pageSize,
currentPage * pageSize,
);
const visible =
visibleColumns === "all"
? new Set(workerColumnIds)
: visibleColumns;
const selectedCount = selected === "all" ? sorted.length : selected.size;
const allColumns: DataGridColumn[] = [
{
accessorKey: "workerId",
allowsSorting: true,
cell: (worker) => {worker.workerId} ,
header: "Worker ID",
id: "workerId",
isRowHeader: true,
minWidth: 100,
},
{
accessorKey: "externalWorkerId",
allowsSorting: true,
cell: (worker) => {worker.externalWorkerId} ,
header: "External Worker ID",
id: "externalWorkerId",
minWidth: 160,
},
{
accessorKey: "name",
allowsSorting: true,
cell: (worker) => (
{worker.name
.split(" ")
.map((part) => part[0])
.join("")}
),
header: "Member",
id: "name",
minWidth: 220,
pinned: "start",
},
{
accessorKey: "country",
allowsSorting: true,
cell: (worker) =>
{worker.status}
),
header: "Status",
id: "status",
minWidth: 100,
},
{
accessorKey: "startDate",
allowsSorting: true,
cell: (worker) => (
{
setValue(String([...keys][0] ?? "all"));
setPage(1);
}}
>
{items.map(([id, label]) => (
{label}
))}
);
return (
{workers.length}
{
setQuery(value);
setPage(1);
}}
>
{filterMenu(type, setType, [
["all", "All"],
["employee", "Employee"],
["contractor", "Contractor"],
])}
{filterMenu(status, setStatus, [
["all", "All"],
["active", "Active"],
["inactive", "Inactive"],
["vacation", "Vacation"],
])}
{
const column = [...keys][0];
if (column)
setSort((current) => ({
column,
direction:
current.column === column &&
current.direction === "ascending"
? "descending"
: "ascending",
}));
}}
>
{allColumns
.filter((column) => column.allowsSorting)
.map((column) => (
{column.header}
))}
{allColumns
.filter((column) => column.id !== "actions")
.map((column) => (
{column.header}
))}
{selectedCount > 0 ? (
<>
worker.id}
selectedKeys={selected}
selectionMode="multiple"
sortDescriptor={sort}
variant="primary"
onSelectionChange={setSelected}
onSortChange={setSort}
/>
setPage((value) => Math.max(1, value - 1))}
>
{paginationPages.map((value, index) =>
value === "ellipsis" ? (
) : (
setPage(value)}
>
{value}
),
)}
setPage((value) => Math.min(pageCount, value + 1))
}
>
);
};
```
### Drag And Drop Reorder
{/* DEMO data-grid-drag-and-drop-reorder */}
```tsx
"use client";
import { useState } from "react";
import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";
import { Chip } from "@thenamespace/uikit/chip";
type Task = {
assignee: string;
id: string;
priority: "high" | "low" | "medium";
status: "done" | "in-progress" | "todo";
title: string;
};
const tasks: Task[] = [
{
assignee: "Olivia",
id: "task-1",
priority: "high",
status: "in-progress",
title: "Design system audit",
},
{
assignee: "Jackson",
id: "task-2",
priority: "high",
status: "todo",
title: "API rate limiting",
},
{
assignee: "Isabella",
id: "task-3",
priority: "medium",
status: "in-progress",
title: "Onboarding flow redesign",
},
{
assignee: "William",
id: "task-4",
priority: "high",
status: "todo",
title: "Database migration script",
},
{
assignee: "Sofia",
id: "task-5",
priority: "low",
status: "done",
title: "Unit test coverage report",
},
{
assignee: "Liam",
id: "task-6",
priority: "medium",
status: "todo",
title: "Performance profiling",
},
{
assignee: "Emma",
id: "task-7",
priority: "medium",
status: "in-progress",
title: "Accessibility audit",
},
{
assignee: "Noah",
id: "task-8",
priority: "low",
status: "done",
title: "CI pipeline optimization",
},
];
const priorityColor = {
high: "danger",
low: "default",
medium: "warning",
} as const;
const taskStatusColor = {
done: "success",
"in-progress": "warning",
todo: "default",
} as const;
const taskStatusLabel = {
done: "Done",
"in-progress": "In Progress",
todo: "To Do",
} as const;
const taskColumns: DataGridColumn[] = [
{
accessorKey: "title",
header: "Task",
id: "title",
isRowHeader: true,
},
{
accessorKey: "priority",
cell: (task) => (
{task.priority}
),
header: "Priority",
id: "priority",
},
{ accessorKey: "assignee", header: "Assignee", id: "assignee" },
{
accessorKey: "status",
cell: (task) => (
{taskStatusLabel[task.status]}
),
header: "Status",
id: "status",
},
];
export const DemoDragAndDropReorderExample = function Demo() {
const [data, setData] = useState(tasks);
return (
task.id}
variant="primary"
onReorder={(event) => setData(event.reorderedData)}
/>
);
};
```
### Pinned Columns Compact
{/* DEMO data-grid-pinned-columns-compact */}
```tsx
"use client";
import type { Selection } from "react-aria-components";
import { useMemo, useState } from "react";
import {
ArrowDown01Icon,
CircleIcon,
FilterIcon,
Link01Icon,
SlidersHorizontalIcon,
} from "@thenamespace/uikit/icons";
import { HugeiconsIcon } from "@thenamespace/uikit/icons";
import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";
import { Button } from "@thenamespace/uikit/button";
import { Dropdown } from "@thenamespace/uikit/dropdown";
import { Input } from "@thenamespace/uikit/input";
import { SearchField } from "@thenamespace/uikit/search-field";
import { Separator } from "@thenamespace/uikit/separator";
type Company = {
categories: string[];
connectionStrength:
| "No communication"
| "Strong"
| "Very strong"
| "Very weak"
| "Weak";
country: string;
dotColor: string;
id: number;
lastInteraction: null | string;
linkedin: string;
name: string;
twitterFollowers: number;
twitterHandle: string;
};
const categoryClasses: Record = {
Airlines: "bg-cyan-100 text-cyan-700 dark:bg-cyan-500/15 dark:text-cyan-400",
Automation:
"bg-teal-100 text-teal-700 dark:bg-teal-500/15 dark:text-teal-400",
B2B: "bg-violet-100 text-violet-700 dark:bg-violet-500/15 dark:text-violet-400",
B2C: "bg-orange-100 text-orange-700 dark:bg-orange-500/15 dark:text-orange-400",
Broadcasting: "bg-red-100 text-red-700 dark:bg-red-500/15 dark:text-red-400",
"Consumer Discretionary":
"bg-pink-100 text-pink-700 dark:bg-pink-500/15 dark:text-pink-400",
"Consumer Electronics":
"bg-pink-100 text-pink-700 dark:bg-pink-500/15 dark:text-pink-400",
"E-commerce":
"bg-emerald-100 text-emerald-700 dark:bg-emerald-500/15 dark:text-emerald-400",
Enterprise:
"bg-blue-100 text-blue-700 dark:bg-blue-500/15 dark:text-blue-400",
Finance: "bg-sky-100 text-sky-700 dark:bg-sky-500/15 dark:text-sky-400",
"Financial Services":
"bg-sky-100 text-sky-700 dark:bg-sky-500/15 dark:text-sky-400",
Food: "bg-yellow-100 text-yellow-700 dark:bg-yellow-500/15 dark:text-yellow-400",
ISP: "bg-slate-100 text-slate-700 dark:bg-slate-500/15 dark:text-slate-400",
"Information Technology":
"bg-gray-100 text-gray-700 dark:bg-gray-500/15 dark:text-gray-400",
Internet: "bg-rose-100 text-rose-700 dark:bg-rose-500/15 dark:text-rose-400",
Marketplace:
"bg-amber-100 text-amber-700 dark:bg-amber-500/15 dark:text-amber-400",
Mobile:
"bg-fuchsia-100 text-fuchsia-700 dark:bg-fuchsia-500/15 dark:text-fuchsia-400",
Performance:
"bg-orange-100 text-orange-700 dark:bg-orange-500/15 dark:text-orange-400",
Publishing:
"bg-lime-100 text-lime-700 dark:bg-lime-500/15 dark:text-lime-400",
SaaS: "bg-indigo-100 text-indigo-700 dark:bg-indigo-500/15 dark:text-indigo-400",
Transportation:
"bg-cyan-100 text-cyan-700 dark:bg-cyan-500/15 dark:text-cyan-400",
};
const companies: Company[] = [
{
categories: ["B2C", "Consumer Discretionary", "E-commerce"],
connectionStrength: "No communication",
country: "US",
dotColor: "bg-amber-500",
id: 1,
lastInteraction: null,
linkedin: "lvmh",
name: "LVMH",
twitterFollowers: 198135,
twitterHandle: "LVMH",
},
{
categories: ["B2C", "E-commerce"],
connectionStrength: "No communication",
country: "US",
dotColor: "bg-emerald-500",
id: 2,
lastInteraction: null,
linkedin: "disneymusicgroup",
name: "Disney",
twitterFollowers: 10140332,
twitterHandle: "Disney",
},
{
categories: [
"B2C",
"Finance",
"Financial Services",
"Information Technology",
],
connectionStrength: "No communication",
country: "US",
dotColor: "bg-blue-500",
id: 3,
lastInteraction: null,
linkedin: "paypal",
name: "PayPal",
twitterFollowers: 969425,
twitterHandle: "PayPal",
},
{
categories: ["Airlines", "B2C", "E-commerce", "Transportation"],
connectionStrength: "No communication",
country: "US",
dotColor: "bg-sky-500",
id: 4,
lastInteraction: null,
linkedin: "united-airlines",
name: "United Airlines",
twitterFollowers: 1174209,
twitterHandle: "united",
},
{
categories: ["B2C", "Consumer Electronics", "E-commerce"],
connectionStrength: "No communication",
country: "US",
dotColor: "bg-gray-800 dark:bg-gray-300",
id: 5,
lastInteraction: null,
linkedin: "apple",
name: "Apple",
twitterFollowers: 9119742,
twitterHandle: "Apple",
},
{
categories: ["B2B", "Enterprise", "Information Technology", "Publishing"],
connectionStrength: "No communication",
country: "US",
dotColor: "bg-red-500",
id: 6,
lastInteraction: null,
linkedin: "microsoft",
name: "Microsoft",
twitterFollowers: 12814907,
twitterHandle: "Microsoft",
},
{
categories: ["B2C", "Internet", "Marketplace"],
connectionStrength: "No communication",
country: "US",
dotColor: "bg-rose-500",
id: 7,
lastInteraction: null,
linkedin: "airbnb",
name: "Airbnb",
twitterFollowers: 883549,
twitterHandle: "Airbnb",
},
{
categories: ["B2C", "E-commerce", "Food", "Marketplace"],
connectionStrength: "Very strong",
country: "US",
dotColor: "bg-green-500",
id: 8,
lastInteraction: "about 2 hours ago",
linkedin: "sweetgreen",
name: "sweetgreen",
twitterFollowers: 3200,
twitterHandle: "sweetgreen",
},
{
categories: ["B2B", "B2C", "SaaS", "Internet", "ISP"],
connectionStrength: "Weak",
country: "US",
dotColor: "bg-indigo-500",
id: 9,
lastInteraction: "2 days ago",
linkedin: "openphone",
name: "OpenPhone",
twitterFollowers: 8400,
twitterHandle: "OpenPhone",
},
{
categories: ["B2B", "B2C", "E-commerce", "Information Technology"],
connectionStrength: "No communication",
country: "UK",
dotColor: "bg-blue-600",
id: 10,
lastInteraction: null,
linkedin: "intercom",
name: "Intercom",
twitterFollowers: 42427,
twitterHandle: "intercom",
},
{
categories: ["Automation", "B2B", "Enterprise", "Information Technology"],
connectionStrength: "Very weak",
country: "UK",
dotColor: "bg-purple-500",
id: 11,
lastInteraction: "about 3 hours ago",
linkedin: "attio",
name: "Attio",
twitterFollowers: 1340,
twitterHandle: "attio",
},
{
categories: [
"B2B",
"B2C",
"Information Technology",
"Mobile",
"Performance",
],
connectionStrength: "Very weak",
country: "DE",
dotColor: "bg-red-600",
id: 12,
lastInteraction: "14 days ago",
linkedin: "opera-software",
name: "Opera",
twitterFollowers: 63000,
twitterHandle: "opera",
},
{
categories: ["B2B", "B2C", "Broadcasting", "Information Technology"],
connectionStrength: "Weak",
country: "US",
dotColor: "bg-blue-500",
id: 13,
lastInteraction: "9 days ago",
linkedin: "google",
name: "Google",
twitterFollowers: 28946065,
twitterHandle: "Google",
},
];
const strengthRank: Record = {
"No communication": 0,
"Very weak": 1,
Weak: 2,
Strong: 3,
"Very strong": 4,
};
const strengthClasses: Record<
Company["connectionStrength"],
{ color: string; dot: string }
> = {
"No communication": { color: "text-muted", dot: "text-muted" },
Strong: {
color: "text-emerald-600 dark:text-emerald-400",
dot: "text-emerald-500",
},
"Very strong": {
color: "text-emerald-600 dark:text-emerald-400",
dot: "text-emerald-500",
},
"Very weak": { color: "text-red-600 dark:text-red-400", dot: "text-red-500" },
Weak: { color: "text-amber-600 dark:text-amber-400", dot: "text-amber-500" },
};
function CompanyCategories({ categories }: { categories: string[] }) {
const shown = categories.slice(0, 3);
const remaining = categories.length - shown.length;
return (
{shown.map((category) => (
{category.length > 14 ? `${category.slice(0, 12)}…` : category}
))}
{remaining > 0 ? (
+{remaining}
) : null}
);
}
function ConnectionStrength({
strength,
}: {
strength: Company["connectionStrength"];
}) {
const classes = strengthClasses[strength];
return (
(new Set());
const [region, setRegion] = useState("all");
const [query, setQuery] = useState("");
const [strength, setStrength] = useState("all");
const filtered = useMemo(() => {
let result = companies;
if (region === "us")
result = result.filter((company) => company.country === "US");
else if (region === "europe")
result = result.filter((company) =>
["UK", "DE", "FR"].includes(company.country),
);
if (strength !== "all")
result = result.filter(
(company) =>
company.connectionStrength.toLowerCase().replace(/\s+/g, "-") ===
strength,
);
if (query) {
const normalized = query.toLowerCase();
result = result.filter(
(company) =>
company.name.toLowerCase().includes(normalized) ||
company.linkedin.toLowerCase().includes(normalized) ||
company.categories.some((category) =>
category.toLowerCase().includes(normalized),
),
);
}
return result;
}, [query, region, strength]);
const companyColumns: DataGridColumn[] = [
{
accessorKey: "name",
allowsSorting: true,
cell: (company) => (
{company.name}
),
header: "Company",
id: "name",
isRowHeader: true,
minWidth: 160,
pinned: "start",
},
{
cell: (company) =>
{
const key = [...keys][0];
if (key) setRegion(String(key));
}}
>
{[
["all", "All Companies"],
["us", "US Companies"],
["europe", "UK & European Co."],
].map(([id, label]) => (
{label}
))}
setStrength(String([...keys][0] ?? "all"))
}
>
{[
["all", "All"],
["very-strong", "Very strong"],
["strong", "Strong"],
["weak", "Weak"],
["very-weak", "Very weak"],
["no-communication", "No communication"],
].map(([id, label]) => (
{label}
))}
company.id}
selectedKeys={selected}
selectionMode="multiple"
variant="primary"
onSelectionChange={setSelected}
/>
{filtered.length} count
);
};
```
### Simple
{/* DEMO data-grid-simple */}
```tsx
"use client";
import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";
import { Button } from "@thenamespace/uikit/button";
import { Link } from "@thenamespace/uikit/link";
type User = {
email: string;
id: number;
name: string;
role: string;
title: string;
};
const users: User[] = [
{
email: "lindsay.walton@example.com",
id: 1,
name: "Lindsay Walton",
role: "Member",
title: "Front-end Developer",
},
{
email: "courtney.henry@example.com",
id: 2,
name: "Courtney Henry",
role: "Admin",
title: "Designer",
},
{
email: "tom.cook@example.com",
id: 3,
name: "Tom Cook",
role: "Member",
title: "Director of Product",
},
{
email: "whitney.francis@example.com",
id: 4,
name: "Whitney Francis",
role: "Admin",
title: "Copywriter",
},
{
email: "leonard.krasner@example.com",
id: 5,
name: "Leonard Krasner",
role: "Owner",
title: "Senior Designer",
},
{
email: "floyd.miles@example.com",
id: 6,
name: "Floyd Miles",
role: "Member",
title: "Principal Designer",
},
];
const userColumns: DataGridColumn[] = [
{
accessorKey: "name",
cellClassName: "font-medium",
header: "Name",
id: "name",
isRowHeader: true,
},
{ accessorKey: "title", header: "Title", id: "title" },
{ accessorKey: "email", header: "Email", id: "email" },
{ accessorKey: "role", header: "Role", id: "role" },
{
align: "end",
cell: () => Edit,
header: "",
id: "edit",
},
];
export const DemoSimpleExample = () => (
user.id}
variant="secondary"
/>
);
```
### Virtualized
{/* DEMO data-grid-virtualized */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import type { Selection } from "react-aria-components";
import { useMemo, useState } from "react";
import {
CancelCircleIcon,
CheckmarkCircle02Icon,
Clock01Icon,
} from "@thenamespace/uikit/icons";
import { HugeiconsIcon } from "@thenamespace/uikit/icons";
import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";
import { Chip } from "@thenamespace/uikit/chip";
import { Input } from "@thenamespace/uikit/input";
import { Rating } from "@thenamespace/uikit/rating";
import { SearchField } from "@thenamespace/uikit/search-field";
import { Segment } from "@thenamespace/uikit/segment";
type Product = {
cost: number;
id: number;
image: string;
name: string;
price: number;
rating: number;
sku: string;
sold: number;
status: "In Stock" | "Low Stock" | "Out of Stock";
stock: number;
};
const productPrefixes = [
"Wireless",
"Portable",
"Premium",
"Ultra",
"Pro",
"Smart",
"Compact",
"Elite",
"Advanced",
"Slim",
"Turbo",
"Eco",
"Classic",
"Deluxe",
"Mini",
] as const;
const productKinds = [
"Headphones",
"Keyboard",
"Monitor",
"Mouse",
"Speaker",
"Webcam",
"Charger",
"Hub",
"Stand",
"Lamp",
"Microphone",
"Router",
"Cable",
"Tablet",
"Controller",
"Drive",
"Dock",
"Chair",
"Projector",
"Sensor",
] as const;
const productBrands = [
"TechFlow",
"NovaPeak",
"ZenCore",
"PixelForge",
"CloudNine",
"ArcWave",
"PrimeByte",
"EchoLink",
"SwiftEdge",
"NeonPulse",
] as const;
const skuPrefixes = [
"AUD",
"KEY",
"MON",
"MSE",
"SPK",
"CAM",
"ACC",
"NET",
"FRN",
"LGT",
] as const;
const productSeeded = (seed: number) => {
const value = Math.sin(seed) * 10_000;
return value - Math.floor(value);
};
const products: Product[] = Array.from({ length: 1000 }, (_, index) => {
const random = (offset: number) => productSeeded(index * 7 + offset);
const prefix =
productPrefixes[Math.floor(random(1) * productPrefixes.length)]!;
const kind = productKinds[Math.floor(random(2) * productKinds.length)]!;
const brand = productBrands[Math.floor(random(3) * productBrands.length)]!;
const skuPrefix = skuPrefixes[Math.floor(random(4) * skuPrefixes.length)]!;
const availability = random(5);
const status =
availability > 0.7
? "In Stock"
: availability > 0.25
? "Low Stock"
: "Out of Stock";
const price = Math.round(20 + random(6) * 2000);
return {
cost: Math.round(price * (0.3 + random(7) * 0.4)),
id: index + 1,
image: `/assets/generated/avatar-${(index % 26) + 1}.jpg`,
name: `${brand} ${prefix} ${kind}`,
price,
rating: Math.round((2.5 + random(10) * 2.5) * 10) / 10,
sku: `${skuPrefix}-${String(Math.floor(random(8) * 9000 + 1000))}`,
sold: Math.floor(random(11) * 800) + 5,
status,
stock:
status === "Out of Stock"
? 0
: status === "Low Stock"
? Math.floor(random(9) * 5) + 1
: Math.floor(random(9) * 200) + 5,
};
});
const productStatusColor = {
"In Stock": "success",
"Low Stock": "warning",
"Out of Stock": "danger",
} as const;
const productStatusIcon = {
"In Stock": CheckmarkCircle02Icon,
"Low Stock": Clock01Icon,
"Out of Stock": CancelCircleIcon,
} as const;
const formatWholeCurrency = (value: number) =>
new Intl.NumberFormat("en-US", {
currency: "USD",
maximumFractionDigits: 0,
style: "currency",
}).format(value);
export const DemoVirtualizedExample = function Demo() {
const [query, setQuery] = useState("");
const [status, setStatus] = useState("all");
const [selected, setSelected] = useState(new Set());
const filtered = useMemo(() => {
const statusNames = {
"in-stock": "In Stock",
"low-stock": "Low Stock",
"out-of-stock": "Out of Stock",
} as const;
let current = products;
if (status !== "all")
current = current.filter(
(product) =>
product.status === statusNames[status as keyof typeof statusNames],
);
if (query) {
const normalized = query.toLowerCase();
current = current.filter(
(product) =>
product.name.toLowerCase().includes(normalized) ||
product.sku.toLowerCase().includes(normalized),
);
}
return current;
}, [query, status]);
const profit = useMemo(
() =>
filtered.reduce(
(total, product) =>
total + (product.price - product.cost) * product.sold,
0,
),
[filtered],
);
const sales = useMemo(
() => filtered.reduce((total, product) => total + product.sold, 0),
[filtered],
);
const productColumns: DataGridColumn[] = [
{
accessorKey: "name",
cell: (product) => (
{product.name}
),
header: "Product",
id: "name",
isRowHeader: true,
minWidth: 280,
},
{
accessorKey: "sku",
cellClassName: "text-muted font-mono text-xs",
header: "SKU",
id: "sku",
},
{
accessorKey: "status",
cell: (product) => (
{product.status}
),
header: "Status",
id: "status",
minWidth: 140,
},
{ accessorKey: "stock", align: "center", header: "Stock", id: "stock" },
{
accessorKey: "price",
align: "end",
cell: (product) => (
{formatWholeCurrency(product.price)}
),
header: "Price",
id: "price",
},
{
accessorKey: "cost",
align: "end",
cell: (product) => (
{formatWholeCurrency(product.cost)}
),
cellClassName: "text-muted",
header: "Cost",
id: "cost",
},
{
accessorKey: "rating",
cell: (product) => (
{[1, 2, 3, 4, 5].map((value) => (
),
header: "Rating",
id: "rating",
},
{
accessorKey: "sold",
align: "end",
cell: (product) => (
{product.sold.toLocaleString()}
),
header: "Sales",
id: "sold",
},
];
const selectedCount = selected === "all" ? filtered.length : selected.size;
return (
All
In Stock
Out of Stock
Low Stock
product.id}
headingHeight={37}
renderEmptyState={() => "No products match the current filters."}
rowHeight={58}
selectedKeys={selected}
selectionMode="multiple"
variant="primary"
onSelectionChange={setSelected}
/>
);
};
```
### With Charts
{/* DEMO data-grid-with-charts */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import type { Selection, SortDescriptor } from "react-aria-components";
import { useMemo, useState } from "react";
import {
Copy01Icon,
FilterIcon,
MoreVerticalIcon,
LayoutThreeColumnIcon,
SlidersHorizontalIcon,
} from "@thenamespace/uikit/icons";
import { HugeiconsIcon } from "@thenamespace/uikit/icons";
import { DataGrid, type DataGridColumn } from "@thenamespace/uikit";
import { AreaChart } from "@thenamespace/uikit/area-chart";
import { Button } from "@thenamespace/uikit/button";
import { Chip } from "@thenamespace/uikit/chip";
import { Dropdown } from "@thenamespace/uikit/dropdown";
import { Input } from "@thenamespace/uikit/input";
import { ProgressCircle } from "@thenamespace/uikit/progress-circle";
import { SearchField } from "@thenamespace/uikit/search-field";
import { Tooltip } from "@thenamespace/uikit/tooltip";
const formatCurrency = (value: number) =>
new Intl.NumberFormat("en-US", {
currency: "USD",
style: "currency",
}).format(value);
function StoryIcon({ icon }: { icon: typeof MoreVerticalIcon }) {
return
{value.toFixed(2)}%
);
}
let sparklineId = 0;
function RequestsSparkline({ data }: { data: { value: number }[] }) {
const gradientId = useMemo(() => `server-spark-${++sparklineId}`, []);
return (
);
}
export const DemoWithChartsExample = function Demo() {
const [query, setQuery] = useState("");
const [selected, setSelected] = useState(new Set());
const [sort, setSort] = useState({
column: "clusterId",
direction: "ascending",
});
const [status, setStatus] = useState("all");
const [visibleColumns, setVisibleColumns] = useState(
new Set(serverColumnIds),
);
const filtered = useMemo(() => {
let result = servers;
if (query) {
const normalized = query.toLowerCase();
result = result.filter(
(server) =>
server.clusterId.toLowerCase().includes(normalized) ||
server.region.toLowerCase().includes(normalized),
);
}
if (status !== "all")
result = result.filter(
(server) => server.status.toLowerCase() === status,
);
return result.toSorted((left, right) => {
const key = sort.column as keyof Server;
const leftValue = left[key];
const rightValue = right[key];
const comparison =
typeof leftValue === "number" && typeof rightValue === "number"
? leftValue - rightValue
: String(leftValue).localeCompare(String(rightValue));
return sort.direction === "descending" ? -comparison : comparison;
});
}, [query, sort, status]);
const visible =
visibleColumns === "all"
? new Set(serverColumnIds)
: visibleColumns;
const allColumns: DataGridColumn[] = [
{
accessorKey: "clusterId",
allowsSorting: true,
cell: (server) =>
{server.status}
),
header: "Status",
id: "status",
},
{
accessorKey: "region",
allowsSorting: true,
header: "Region",
id: "region",
},
{
accessorKey: "capacity",
allowsSorting: true,
cell: (server) =>
{servers.length}
setStatus(String([...keys][0] ?? "all"))
}
>
{[
["all", "All"],
["active", "Active"],
["inactive", "Inactive"],
].map(([id, label]) => (
{label}
))}
{
const column = [...keys][0];
if (!column) return;
setSort((current) => ({
column,
direction:
current.column === column &&
current.direction === "ascending"
? "descending"
: "ascending",
}));
}}
>
{allColumns
.filter((column) => column.allowsSorting)
.map((column) => (
{column.header}
))}
{allColumns.map((column) => (
{column.header}
))}
server.id}
selectedKeys={selected}
selectionMode="multiple"
sortDescriptor={sort}
variant="primary"
onSelectionChange={setSelected}
onSortChange={setSort}
/>
);
};
```
## CSS Classes
### Base Classes
- `.data-grid` — Root wrapper. Sets `position: relative` and `width: 100%`. Defines `--data-grid-selection-column-width` and `--data-grid-drag-handle-column-width` custom properties.
### Element Classes
- `.data-grid__selection-column` — Narrow `` for the select-all checkbox. Fixed width from `--data-grid-selection-column-width`.
- `.data-grid__selection-cell` — Narrow ` ` for row selection checkboxes. Same fixed width.
- `.data-grid__drag-handle-column` — Narrow ` ` for the drag handle column. Fixed width from `--data-grid-drag-handle-column-width`.
- `.data-grid__drag-handle-cell` — Narrow ` ` for the drag handle. Same fixed width.
- `.data-grid__drag-handle` — The grip button inside each row. Styled with `cursor: grab` and subtle color.
- `.data-grid__sort-icon` — Chevron indicator next to sortable column headers. Rotates 180° when descending.
- `.data-grid__empty-state` — Centered container for the empty state message. Muted text, vertical padding.
- `.data-grid__tree-cell` — Flex wrapper inside the `treeColumn` cell that holds the chevron toggle and cell content. Per-level indentation is applied inline via `padding-inline-start`.
- `.data-grid__tree-toggle` — Expand/collapse chevron button, rendered when a row has children. Sized via `--data-grid-tree-toggle-size`.
- `.data-grid__tree-toggle-icon` — Chevron icon inside the toggle. Rotates 90° when the row is expanded via `[data-expanded]`.
- `.data-grid__tree-toggle-spacer` — Invisible placeholder rendered for leaf rows so their content aligns with sibling rows that have a chevron.
### Interactive States
- **Drag handle hover**: `&:hover` / `[data-hovered="true"]` on `.data-grid__drag-handle` — text transitions to `foreground`.
- **Drag handle pressed**: `&:active` / `[data-pressed="true"]` on `.data-grid__drag-handle` — cursor changes to `grabbing`.
- **Drag handle focus**: `[data-focus-visible="true"]` on `.data-grid__drag-handle` — applies focus ring via `status-focused`.
- **Row dragging**: `.table__row[data-dragging="true"]` — reduced opacity (0.5).
- **Drop indicator**: `.react-aria-DropIndicator[data-drop-target] td` — accent background line.
### Alignment
- `[data-align="end"]` — Right-aligns both header and cell content.
- `[data-align="center"]` — Center-aligns both header and cell content.
### Vertical Alignment
Controlled by the `verticalAlign` prop via `[data-vertical-align]` on the root:
- `[data-vertical-align="top"]` — `vertical-align: top` (flexbox `items-start` in virtualized mode).
- `[data-vertical-align="middle"]` — `vertical-align: middle` (flexbox `items-center` in virtualized mode).
- `[data-vertical-align="bottom"]` — `vertical-align: bottom` (flexbox `items-end` in virtualized mode).
### Pinned Columns
- `[data-pinned]` — Makes the cell `position: sticky` with `z-index: 2`.
- `[data-pinned="start"]` — Sticky to `inset-inline-start`.
- `[data-pinned="end"]` — Sticky to `inset-inline-end`.
- `[data-pinned-edge]` — Boundary column that shows a separator line when the pinned group detaches from the scrollable content.
- `[data-pinned-start-detached]` — Set on root when content has scrolled past the start-pinned columns. Shows separator via `::after`.
- `[data-pinned-end-detached]` — Set on root when content hasn't scrolled to the end edge. Shows separator via `::after`.
### CSS Variables
- `--data-grid-selection-column-width` — Width of the selection checkbox column (default: `40px`).
- `--data-grid-drag-handle-column-width` — Width of the drag handle column (default: `32px`).
- `--data-grid-tree-toggle-size` — Size of the expand/collapse chevron button and its leaf-row spacer (default: `24px`).
- `--data-grid-tree-gap` — Gap between the chevron/spacer and the cell content in a `treeColumn` cell (default: `4px`).
## API Reference
### DataGrid
The root data grid component. Accepts a generic type parameter `T` for the row data shape.
| Prop | Type | Default | Description |
| -------------------------- | ----------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `data` | `T[]` | — | Row data array. |
| `columns` | `DataGridColumn[]` | — | Column definitions. |
| `getRowId` | `(item: T) => string \| number` | — | Extracts a unique key from each row item. |
| `aria-label` | `string` | — | Accessible label for the table. Required. |
| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant passed to the underlying Table. |
| `className` | `string` | — | Additional className for the root wrapper. |
| `contentClassName` | `string` | — | Additional className for the inner `` element (e.g. `min-w-[1200px]` for horizontal scroll). |
| `scrollContainerClassName` | `string` | — | Additional className for the scroll container (e.g. `max-h-[400px] overflow-y-auto`). |
| `verticalAlign` | `"top" \| "middle" \| "bottom"` | `"middle"` | Vertical alignment of cell content within each row. |
| `selectionMode` | `"none" \| "single" \| "multiple"` | `"none"` | Row selection mode. |
| `selectedKeys` | `Selection` | — | Controlled selected row keys. |
| `defaultSelectedKeys` | `Selection` | — | Default selected row keys (uncontrolled). |
| `onSelectionChange` | `(keys: Selection) => void` | — | Callback when selection changes. |
| `selectionBehavior` | `"toggle" \| "replace"` | `"toggle"` | Selection interaction model. |
| `showSelectionCheckboxes` | `boolean` | `false` | Auto-prepend a checkbox column for selection. |
| `sortDescriptor` | `SortDescriptor` | — | Controlled sort descriptor. When provided, sorting is controlled externally. |
| `defaultSortDescriptor` | `SortDescriptor` | — | Default sort descriptor (uncontrolled). |
| `onSortChange` | `(descriptor: SortDescriptor) => void` | — | Callback when sort changes. Fires in both controlled and uncontrolled modes. |
| `allowsColumnResize` | `boolean` | `false` | Enable column resizing on columns that opt in. |
| `onColumnResize` | `(widths: Map
{payment.customer}
{payment.email}
),
header: "Customer",
id: "customer",
isRowHeader: true,
minWidth: 200,
},
{
accessorKey: "id",
allowsResizing: true,
cellClassName: "font-mono text-xs text-muted",
header: "Transaction ID",
id: "id",
minWidth: 130,
},
{
accessorKey: "status",
allowsResizing: true,
allowsSorting: true,
cell: (payment) => (
{count} of {payments.length} row(s) selected
) : null}
{value}
);
}
export const DemoEditableCellsExample = function Demo() {
const [data, setData] = useState(features);
const update = (id: string, values: PartialFeature Flags
Edit titles, change priorities, adjust story points, and toggle features inline.
{enabled} of {data.length} enabled
Total effort: {effort} pts
Projects
Invoices
{data.length > 0 ? (
{employee.name}
{employee.email}
{country.name}
);
}
function TeamChips({ teams }: { teams: string[] }) {
return (
{teams.slice(0, 3).map((team) => (
{worker.name}
{worker.email}
Team Members
{query ? (
Search: {query}
) : null}
{type !== "all" ? (
Type: {type}
) : null}
{status !== "all" ? (
Status: {status}
) : null}
) : null}
Drag rows to reorder. Use keyboard (Enter to grab, arrows to move, Enter to drop).
Companies
Users
A list of all the users in your account including their name, title, email and role.
{filtered.length.toLocaleString()} products
{selectedCount > 0
? ` · ${selectedCount.toLocaleString()} selected`
: null}
Profit:{" "}
{formatWholeCurrency(profit)}
Sales:{" "}
{sales.toLocaleString()}
{value}
Copy
);
}
function Capacity({ value }: { value: number }) {
const color =
value >= 90
? "danger"
: value >= 60
? "warning"
: value >= 20
? "accent"
: "default";
const textColor =
value >= 90 ? "text-danger" : value >= 60 ? "text-warning" : "";
return (
Servers
| ` for this column. | | `cellClassName` | `string` | — | Additional className appended to every ` | ` for this column. |
| `pinned` | `"start" \| "end"` | — | Pin this column so it stays visible during horizontal scroll. Uses logical directions (start = left in LTR). Pinned columns must have a numeric `width` or `minWidth`. |
### DataGridReorderEvent\ Determines the smallest unit displayed in the date picker. By default, this is "day" for dates, and "minute" for times. Scan this QR code with your camera app to preview the Namespace UIKit native components. 
Expo must be installed on your device. Download the Namespace UIKit native app to explore our mobile components directly on your device.
Available on iOS and Android devices. Namespace UIKit NativeScan this QR code with your camera app to preview the Namespace UIKit native components.
Expo must be installed on your device. Scan this QR code with your camera app to preview the Namespace UIKit native components.
Expo must be installed on your device. Scan this QR code with your camera app to preview the Namespace UIKit native components.
Expo must be installed on your device. Scan this QR code with your camera app to preview the Namespace UIKit native components.
Expo must be installed on your device. This is a bottom drawer built with React Aria's Modal component. It slides up from the bottom of the screen with a smooth CSS transition.
{placements.map((placement) => (
);
}
```
### Backdrop Variants
```tsx
import {Button, Drawer} from "@thenamespace/uikit";
export function BackdropVariants() {
const variants = ["opaque", "blur", "transparent"] as const;
return (
This drawer slides in from the {placement} edge of the screen.
{variants.map((variant) => (
);
}
```
### Non-Dismissable
Set `isDismissable={false}` on `Drawer.Backdrop` to prevent closing by clicking outside or dragging. The user must interact with the drawer's action buttons.
```tsx
import {Button, Drawer} from "@thenamespace/uikit";
export function NonDismissable() {
return (
This drawer uses the This drawer cannot be dismissed by clicking outside or dragging. You must use one of the buttons below. Paragraph {i + 1}: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. ))}With React.useState()
Control the drawer using React's Status:{" "} {isOpen ? "open" : "closed"}
This drawer is controlled by React's With useOverlayState()
Use the Status:{" "} {state.isOpen ? "open" : "closed"}
The This drawer has custom styling applied via Tailwind classes.
{" | "}
)}
{error} : null}Selected: {selectedItems.length > 0 ? selectedItems.join(", ") : "None"} Dropdown is: {open ? "open" : "closed"} Jane Doe jane@example.com
{categories.map(({ icon, id, label }) => (
{label}
{categories.map(({ icon, id, label }) => (
{label}
{categories.map(({ icon, id, label }) => (
{label}
{categories.map(({ icon, id, label }) => (
{label}
{(["sm", "md", "lg"] as const).map((size) => (
);
}
export const DemoSizesExample = () =>
{size}
))}
`.
### EmojiPicker.SkinTonePicker
Root provider for the skin tone selector. Manages a `Popover` internally.
| Prop | Type | Default | Description |
| -------------- | ------------------------- | ----------- | ------------------------------------ |
| `value` | `string` | — | Controlled skin tone value. |
| `defaultValue` | `string` | `"default"` | Default skin tone (uncontrolled). |
| `onChange` | `(value: string) => void` | — | Callback when the skin tone changes. |
### EmojiPicker.SkinToneTrigger
Button that opens the skin tone popover. Shows the current skin tone emoji.
| Prop | Type | Default | Description |
| ------------ | --------------------- | -------------------- | ------------------------------------------------------- |
| `tones` | `EmojiSkinToneItem[]` | `EMOJI_SKIN_TONES` | Skin tone data for resolving the current value's emoji. |
| `aria-label` | `string` | `"Select skin tone"` | Accessible label. |
### EmojiPicker.SkinToneContent
Popover content for the skin tone selector.
| Prop | Type | Default | Description |
| ----------- | ----------- | -------------- | -------------------------- |
| `offset` | `number` | `4` | Distance from the trigger. |
| `placement` | `Placement` | `"bottom end"` | Popover placement. |
### EmojiPicker.SkinToneOption
An individual skin tone swatch button.
| Prop | Type | Default | Description |
| ---- | -------- | ------- | ------------------------------------------------------------------------ |
| `id` | `string` | — | Skin tone identifier (e.g., `"default"`, `"light"`, `"dark"`). Required. |
{Object.entries(reactions).map(([emoji, item]) => (
);
};
```
## Anatomy
Import the EmojiReactionButton component and access all parts using dot notation.
```tsx
import { EmojiReactionButton } from "@thenamespace/uikit";
{(["sm", "md", "lg"] as const).map((size) => (
);
```
## CSS Classes
### Base & Size Classes
- `.emoji-reaction-button` - Base toggle button with rounded-full shape
- `.emoji-reaction-button--sm` - Small size
- `.emoji-reaction-button--md` - Medium size (default)
- `.emoji-reaction-button--lg` - Large size
### Element Classes
- `.emoji-reaction-button__emoji` - The emoji character
- `.emoji-reaction-button__count` - The reaction count
### Interactive States
- **Selected**: `[data-selected="true"]` on root (accent border and background tint; count text turns accent)
- **Hover**: `:hover` or `[data-hovered="true"]` (background change)
- **Focus visible**: `:focus-visible` or `[data-focus-visible="true"]` (focus ring)
- **Pressed**: `:active` or `[data-pressed="true"]` (scale down)
- **Read-only**: `[data-readonly="true"]` on root (default cursor, no press scale, no pointer interaction)
- **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity)
## API Reference
### EmojiReactionButton
The root component. Wraps RAC [ToggleButton](https://react-spectrum.adobe.com/react-aria/ToggleButton.html).
| Prop | Type | Default | Description |
| ----------------- | ------------------------------------------- | ------- | -------------------------------------------------------------------------- |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant |
| `isSelected` | `boolean` | - | Whether the button is selected (controlled) |
| `defaultSelected` | `boolean` | - | Default selected state (uncontrolled) |
| `onChange` | `(isSelected: boolean) => void` | - | Handler called when the selected state changes |
| `isReadOnly` | `boolean` | - | Whether the button is read-only and should not respond to user interaction |
| `isDisabled` | `boolean` | - | Whether the button is disabled |
| `children` | `ReactNode \| ((renderProps) => ReactNode)` | - | Emoji and Count elements |
Also supports all RAC [ToggleButton](https://react-spectrum.adobe.com/react-aria/ToggleButton.html) props.
### EmojiReactionButton.Emoji
The emoji character display.
Also supports all native `span` HTML attributes.
### EmojiReactionButton.Count
The reaction count display.
Also supports all native `span` HTML attributes.
{size}
))}
{(["sm", "md", "lg"] as const).map((size) => (
);
}
export const DemoSizesExample = () =>
{size}
))}
{error}
))}
No files }
selectionMode="multiple"
>
{renderNode}
{(["sm", "md", "lg"] as const).map((size) => (
);
```
## Guide Lines
{/* DEMO file-tree-guide-lines */}
```tsx
"use client";
import { FileTree, type FileTreeItemRenderProps } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
const FolderIcon = ({ isExpanded }: FileTreeItemRenderProps) => (
{size}
))}
{([true, "hover", false] as const).map((value) => (
);
```
## Multiple Selection
{/* DEMO file-tree-multiple-selection */}
```tsx
// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";
import { useState } from "react";
import { FileTree } from "@thenamespace/uikit";
import { type Selection } from "react-aria-components";
function MultipleSelectionDemo() {
const [selectedKeys, setSelectedKeys] = useState
{value === true ? "always" : value === false ? "none" : "hover"}
))}
Selected:{" "} {selectedKeys === "all" ? "all" : [...selectedKeys].join(", ") || "none"} ` internally.
| Prop | Type | Default | Description |
| ---------------- | ---------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `reduceMotion` | `boolean` | `false` | Disables expand/collapse animation. The user's reduced-motion preference is still respected. |
| `showGuideLines` | `boolean \| "hover"` | `true` | Whether to show indent guide lines. `true` = always, `false` = never, `"hover"` = on tree hover only. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size variant controlling item padding, font size, and indent width. |
Also supports all RAC [Tree](https://react-spectrum.adobe.com/react-aria/Tree.html) props.
### FileTree.Item
An individual tree row representing a file or folder.
| Prop | Type | Default | Description |
| ---------- | -------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `title` | `ReactNode` | — | Label content rendered as the item text. Required. |
| `icon` | `ReactNode \| ((props: FileTreeItemRenderProps) => ReactNode)` | — | Icon rendered before the label. Can be a render function receiving `{ isExpanded, hasChildItems, allowsDragging }`. |
| `dragIcon` | `ReactNode \| false` | `
State: {open ? "open" : "closed"}
{[
{ closeDelay: 0, label: "Instant", openDelay: 0 },
{ closeDelay: 300, label: "Default (200/300)", openDelay: 200 },
{ closeDelay: 500, label: "Slow (600/500)", openDelay: 600 },
].map((config) => (
);
}
export const DemoCustomDelaysExample = () =>
{config.label}
))}
{article.map((item) => (
{item.label}{item.text}
{hierarchy
.filter((item) => item.level === 1)
.map((item) => (
{item.label}Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Namespace UIKit
@thenamespace
Building the future of UI for web & mobile. 🚀 (YC S24) 4 Following 97.1K Followers
Check out{" "}
Namespace UIKit
@thenamespace
Building the future of UI for web & mobile. 🚀 (YC S24) 4 Following 97.1K Followers
State: {open ? "open" : "closed"}
This card is controlled:{" "}
Neo Brutalism Raw aesthetics, bold colors, and playful typography.
{[
{ closeDelay: 0, label: "Instant", openDelay: 0 },
{ closeDelay: 300, label: "Default (700 / 300)", openDelay: 700 },
{ closeDelay: 500, label: "Slow (1s / 500)", openDelay: 1000 },
].map((config) => (
);
```
## Placements
{/* DEMO hover-card-placements */}
```tsx
"use client";
import { HoverCard } from "@thenamespace/uikit";
import { Avatar } from "@thenamespace/uikit/avatar";
import { Button } from "@thenamespace/uikit/button";
function Profile() {
return (
<>
Namespace UIKit
@thenamespace
Building the future of UI for web & mobile. 🚀 (YC S24) 4 Following 97.1K Followers Hover buttons
{(["top", "left", "right", "bottom"] as const).map((placement) => (
Namespace UIKit
@thenamespace
Building the future of UI for web & mobile. 🚀 (YC S24) 4 Following 97.1K Followers
Hover over{" "}
Neo Brutalism Raw aesthetics, bold colors, and playful typography.
Learn more about the{" "}
{letter}
);
}
export const DemoTeamSwitcherExample = function Demo() {
const [value, setValue] = useState("northwind-labs");
const selected = teams.find((team) => team.id === value) ?? teams[0];
return (
Add a files and more Connect apps Voice input Send We've sent a code to a****@gmail.com Didn't receive a code? ResendWe've sent a code to a****@gmail.com Didn't receive a code? Resend
setValue(event.target.value)}
/>
https://{value || "your-domain"}
);
}
```
### Full Width
```tsx
import {Input} from "@thenamespace/uikit";
export function FullWidth() {
return (
{(
["default", "secondary", "tertiary", "outline", "transparent"] as const
).map((variant) => (
);
```
## Wallet List
{/* DEMO item-card-group-wallet-list */}
```tsx
"use client";
import { Fragment } from "react";
import { ItemCardGroup } from "@thenamespace/uikit";
import { Button } from "@thenamespace/uikit/button";
import { ItemCard } from "@thenamespace/uikit/item-card";
import { Separator } from "@thenamespace/uikit/separator";
import { Icon } from "@/demos/icon";
const wallets = [
{
address: "0x34E6...6255",
icon: "hugeicons:wallet",
bg: "bg-neutral-800",
eth: "0.0 ETH",
name: "Funds",
usd: "$0.00",
},
{
address: "0xD9EA...f40e",
icon: "hugeicons:globe",
bg: "bg-blue-500",
eth: "0.0 ETH",
name: "0xD9EA...f40e",
usd: "$0.00",
},
{
address: "0x9DC5...621a",
icon: "hugeicons:planet-earth",
bg: "bg-green-500",
eth: "0.021 ETH",
name: "SLMobbin's",
usd: "$37.09",
},
{
address: "0xa98b...4daa",
icon: "hugeicons:person",
bg: "bg-orange-400",
eth: "0.0 ETH",
name: "Sam Lee's Wallet",
usd: "$0.00",
},
];
export const DemoWalletListExample = () => (
{wallet.usd} {wallet.eth}
{[
["MacBook Pro", "Last active: 2 minutes ago", "solar:smartphone-linear"],
["iMac", "Last active: 3 days ago", "solar:monitor-linear"],
["iPhone 15 Pro", "Last active: 1 hour ago", "solar:shield-check-linear"],
].map(([title, description, icon], index) => (
);
```
## Email Setting
{/* DEMO item-card-email-setting */}
```tsx
"use client";
import { ItemCard } from "@thenamespace/uikit";
import { Button } from "@thenamespace/uikit/button";
import { Chip } from "@thenamespace/uikit/chip";
import { Dropdown } from "@thenamespace/uikit/dropdown";
import { Separator } from "@thenamespace/uikit/separator";
import { Tooltip } from "@thenamespace/uikit/tooltip";
import { Icon } from "@/demos/icon";
const Glyph = ({ icon }: { icon: string }) =>
{(
["default", "secondary", "tertiary", "outline", "transparent"] as const
).map((variant) => (
);
```
## Vertical Stack
{/* DEMO item-card-vertical-stack */}
```tsx
"use client";
import { ItemCard } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
const Glyph = ({ icon }: { icon: string }) =>
{[
["Profile", "Update your personal information", "solar:user-linear"],
["Security", "Manage passwords and 2FA", "solar:key-linear"],
["Cloud sync", "Sync data across your devices", "solar:cloud-linear"],
].map(([title, description, icon]) => (
);
```
## Wallet Card
{/* DEMO item-card-wallet-card */}
```tsx
"use client";
import { ItemCard } from "@thenamespace/uikit";
import { Button } from "@thenamespace/uikit/button";
import { Icon } from "@/demos/icon";
const Glyph = ({ icon }: { icon: string }) => $34.99 0.021 ETH
{ticket.title}
{ticket.description}
{ticket.tags?.length ? (
);
}
function TicketColumn({
column,
kanban,
}: {
column: Ticket["status"];
kanban: UseKanbanReturn
{ticket.tags.map((tag) => (
) : null}
{ticket.progress != null ? (
{ticket.assignees?.length ? (
) : null}
{ticket.assignees.slice(0, 3).map((person) => (
) : (
)}
{ticket.comments || ticket.attachments ? (
{ticket.comments ? (
) : null}
{task.title}
{task.categories.map((category) => (
) : null}
);
}
function NotionColumn({
column,
kanban,
}: {
column: NotionStatus;
kanban: UseKanbanReturn
{task.assignees.slice(0, 3).map((person) => (
{task.dueDate ? (
{task.dueDate}
) : null}
{ticket.title}
{ticket.description}
{ticket.tags?.length ? (
);
}
function SizedTicketColumn({
column,
kanban,
}: {
column: "In Progress" | "Open";
kanban: UseKanbanReturn
{ticket.tags.map((tag) => (
) : null}
{ticket.progress != null ? (
{ticket.assignees?.length ? (
) : null}
{ticket.assignees.slice(0, 3).map((person) => (
) : (
)}
{ticket.comments || ticket.attachments ? (
{ticket.comments ? (
) : null}
{size}
);
}
export const DemoSizesExample = () => (
{(["sm", "md", "lg"] as const).map((size) => (
);
```
## CSS Classes
### Base & Size Classes
- `.kanban` — Root board container. CSS grid with horizontal auto-flow and snap scrolling.
- `.kanban--sm` — Small size. Narrower columns (`240px`), tighter gap (`12px`).
- `.kanban--md` — Medium size (default). Standard columns (`280px`), default gap (`16px`).
- `.kanban--lg` — Large size. Wider columns (`320px`), spacious gap (`20px`).
### Element Classes
- `.kanban__column` — Individual column section. Flex column with snap-center alignment.
- `.kanban__column-body` — Visual container for card list and add button. Rounded with `bg-default/40`.
- `.kanban__column-header` — Header area with indicator, title, count, and action buttons.
- `.kanban__column-actions` — Hover-reveal action buttons inside the header. Fades in on column header hover.
- `.kanban__column-indicator` — Colored status dot (when empty) or icon container (when children are provided).
- `.kanban__column-title` — Column heading text (`text-sm font-semibold`).
- `.kanban__column-count` — Item count badge (`text-xs text-muted`).
- `.kanban__card` — Outer card wrapper (RAC `GridListItem`). Handles focus ring, cursor, and drag opacity.
- `.kanban__card--sm` — Small card variant.
- `.kanban__card--md` — Medium card variant.
- `.kanban__card--lg` — Large card variant.
- `.kanban__card-content` — Inner motion wrapper. Carries background (`bg-overlay`), rounded corners, shadow, and flex layout.
- `.kanban__card-content--sm` — Small card content (`gap-1.5 p-2 text-xs`).
- `.kanban__card-content--md` — Medium card content (`gap-2 p-3 text-sm`). Default.
- `.kanban__card-content--lg` — Large card content (`gap-3 p-4 text-base`).
- `.kanban__card-list` — Scrollable GridList container with vertical gap between cards.
- `.kanban__scroll-shadow` — Optional ScrollShadow wrapper for constrained, scrollable columns.
- `.kanban__drop-indicator` — Custom drop indicator with animated height via `--kanban-drop-height`.
- `.kanban__drag-handle` — Grip button, screen-reader-only by default. Reveals on focus.
- `.kanban__empty` — Empty state placeholder centered inside an empty column.
### Interactive States
- **Hover**: `.kanban__card:hover > .kanban__card-content` — applies `shadow-sm`.
- **Selected**: `.kanban__card[data-selected="true"] > .kanban__card-content` — applies `bg-accent-soft`.
- **Dragging**: `.kanban__card[data-dragging]` — reduced opacity (0.5).
- **Focus visible**: `.kanban__card[data-focus-visible="true"]` — focus ring with `ring-2`.
- **Disabled**: `.kanban__card[aria-disabled="true"]` — disabled opacity.
- **Column actions reveal**: `.kanban__column-header:hover .kanban__column-actions` — opacity transitions to 1.
- **Drop target**: `.kanban__drop-indicator[data-drop-target]` — border and animated height.
- **Drag handle reveal**: `.kanban__card[data-focus-visible="true"] .kanban__drag-handle` — becomes visible (exits `sr-only`).
### CSS Variables
- `--kanban-column-min-width` — Minimum column width (default: `280px`).
- `--kanban-column-gap` — Gap between columns (default: `16px`).
- `--kanban-column-height` — Column height reference (default: `480px`).
- `--kanban-drop-height` — Drop indicator placeholder height. Set automatically by `useKanbanCardPlaceholder`.
## API Reference
### Kanban
The root board container. Wraps children in a horizontal `ScrollShadow` with Motion support.
| Prop | Type | Default | Description |
| ------ | ---------------------- | ------- | ------------------------------------------------------------------- |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size variant controlling card padding, font size, and column width. |
Also supports all [Namespace UIKit ScrollShadow](https://namespace.com/docs/react/components/scroll-shadow) props (except `size`).
### Kanban.Column
An individual column section. Renders a `` with rounded background.
### Kanban.ColumnHeader
Header area containing indicator, title, count, and action buttons. Renders a ` `.
### Kanban.ColumnIndicator
Colored status dot or icon. Renders as a small dot when empty; switches to an icon container when children are provided. Renders a ``.
### Kanban.ColumnTitle
Column heading text. Renders an ` `.
### Kanban.ColumnCount
Item count badge next to the title. Renders a ``.
### Kanban.CardList
The scrollable card list backed by RAC `GridList`.
| Prop | Type | Default | Description |
| ------------------ | ---------------------------------- | -------- | -------------------------------------------------------- |
| `selectionMode` | `"none" \| "single" \| "multiple"` | `"none"` | Selection behavior for cards. |
| `renderEmptyState` | `() => ReactNode` | — | Custom empty state content when the column has no cards. |
Also supports all RAC [GridList](https://react-spectrum.adobe.com/react-aria/GridList.html) props.
### Kanban.Card
An individual draggable card. Wraps content in a Motion `layout` animation for smooth reorder transitions. Backed by RAC `GridListItem`.
| Prop | Type | Default | Description |
| ----------- | ------------------------------------------- | ------- | ------------------------------------------------------------------ |
| `textValue` | `string` | — | Accessible text value for the card. |
| `children` | `ReactNode \| ((renderProps) => ReactNode)` | — | Card content. Can be a render function receiving RAC render props. |
Also supports all RAC [GridListItem](https://react-spectrum.adobe.com/react-aria/GridList.html#gridlistitem) props.
### Kanban.DropIndicator
Visual drop indicator shown during drag operations. Supports animated height sizing.
| Prop | Type | Default | Description |
| -------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `height` | `number` | — | Height of the drop placeholder in pixels. Typically set to the dragged card's height via `--kanban-drop-height`. |
Also supports all RAC [DropIndicator](https://react-spectrum.adobe.com/react-aria/DropIndicator.html) props.
### Kanban.DragHandle
Grip button for keyboard-accessible dragging. Screen-reader-only by default; reveals on focus. Uses `slot="drag"` for RAC drag integration.
Also supports all RAC [Button](https://react-spectrum.adobe.com/react-aria/Button.html) props.
### Kanban.ScrollShadow
Optional scroll wrapper for constrained column heights. Use with `max-h-[...]` to enable vertical scrolling within a column.
Also supports all [Namespace UIKit ScrollShadow](https://namespace.com/docs/react/components/scroll-shadow) props.
### useKanban
A hook that manages the shared list data for the entire board.
```tsx
const kanban = useKanban({
initialItems: tasks,
getColumn: (item) => item.status,
setColumn: (item, column) => ({ ...item, status: column }),
});
```
**Options:**
| Option | Type | Default | Description |
| -------------- | -------------------------------- | ------------------ | ---------------------------------------------------------------------- |
| `initialItems` | `T[]` | — | Items to populate the board with. |
| `getColumn` | `(item: T) => string` | — | Return the column identifier for a given item. |
| `setColumn` | `(item: T, column: string) => T` | — | Return a copy of the item assigned to a new column. |
| `dragType` | `string` | `"kanban-item-id"` | Custom MIME-like drag type for transferring item keys between columns. |
| `getKey` | `(item: T) => string \| number` | `item.id` | Derive a unique key from each item. |
**Returns:**
| Property | Type | Description |
| ------------ | --------------------------------------------------- | ------------------------------------------------------ |
| `list` | `ListData
Arrow Keys:
Page Navigation:
Press{" "}
Use{" "}
Navigate with{" "}
Save your work with{" "}
Quick Actions
Press{" "}
Use{" "}
Hold{" "}
Copy:
Paste:
Cut:
Undo:
Redo:
{cards.map((card) => (
);
```
## Anatomy
Import the KPI component and access all parts using dot notation.
```tsx
import { KPI } from "@thenamespace/uikit";
{[
{
title: "Conversion Rate",
value: 0.038,
trend: "+1.7%",
status: "success",
},
{
title: "Bounce Rate",
value: 0.423,
trend: "-5.9%",
status: "danger",
},
{ title: "Load Time", value: 856, trend: null, status: "warning" },
].map((card) => (
);
```
## With Chart Bottom
{/* DEMO kpi-with-chart-bottom */}
```tsx
"use client";
import { KPI } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
const up = [
{ value: 30 },
{ value: 35 },
{ value: 28 },
{ value: 42 },
{ value: 38 },
{ value: 45 },
{ value: 50 },
{ value: 48 },
{ value: 55 },
{ value: 60 },
{ value: 58 },
{ value: 65 },
];
const down = [
{ value: 65 },
{ value: 60 },
{ value: 62 },
{ value: 55 },
{ value: 58 },
{ value: 52 },
{ value: 50 },
{ value: 48 },
{ value: 45 },
{ value: 42 },
{ value: 44 },
{ value: 40 },
];
export const DemoWithChartBottomExample = () => (
{[
{
title: "Total Clicks",
value: 2441,
trend: "up",
change: "3.5%",
suffix: "last 30d",
data: up,
color: "var(--color-accent)",
},
{
title: "Bounce Rate",
value: 0.423,
trend: "down",
change: "5.9%",
suffix: "vs last 7d",
data: down,
color: "var(--color-danger)",
},
].map((card) => (
);
```
## With Footer
{/* DEMO kpi-with-footer */}
```tsx
"use client";
import { KPI } from "@thenamespace/uikit";
import { Link } from "@thenamespace/uikit/link";
import { Icon } from "@/demos/icon";
export const DemoWithFooterExample = () => (
{[
{
title: "Total Subscribers",
value: 71897,
change: "+122",
status: "success",
href: "View all",
},
{
title: "Monthly Revenue",
value: 45231,
change: "+20.1%",
status: "warning",
href: "View report",
},
].map((card) => (
);
```
## With Icon
{/* DEMO kpi-with-icon */}
```tsx
"use client";
import { KPI } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
export const DemoWithIconExample = () => (
{[
{
title: "Total Users",
value: 5400,
change: "+33%",
trend: "up",
status: "success",
icon: "solar:user-plus-linear",
},
{
title: "Total Sales",
value: 15400,
change: "0.0%",
trend: "neutral",
status: "warning",
icon: "solar:dollar-minimalistic-linear",
},
{
title: "Net Profit",
value: 10400,
change: "-3.3%",
trend: "down",
status: "danger",
icon: "solar:tag-price-linear",
},
].map((card) => (
);
```
## With Progress
{/* DEMO kpi-with-progress */}
```tsx
"use client";
import { KPI } from "@thenamespace/uikit";
import { Icon } from "@/demos/icon";
export const DemoWithProgressExample = () => (
{[
{ title: "Server Load", value: 0.38, progress: 38, status: "success" },
{ title: "Server Load", value: 0.98, progress: 98, status: "danger" },
{
title: "Average Memory Used",
value: 0.64,
progress: 64,
status: "warning",
},
].map((card, index) => (
);
```
## CSS Classes
### Base Classes
- `.kpi` - Base card shell with flex column layout and padding
### Element Classes
- `.kpi__header` - Top row for icon, title, and actions
- `.kpi__content` - Grid layout container for value and trend side by side
- `.kpi__icon` - Status-tinted icon container
- `.kpi__actions` - Absolutely positioned action button area
- `.kpi__title` - Metric label text (`dt` element)
- `.kpi__value` - Large formatted number (`dd` element)
- `.kpi__trend` - Inline trend badge (wraps TrendChip)
- `.kpi__progress` - Full-width progress bar area
- `.kpi__chart` - Sparkline container with edge-fade mask
- `.kpi__separator` - Edge-to-edge divider
- `.kpi__footer` - Bottom section
### Data Attributes
- `[data-status="success"]` / `[data-status="warning"]` / `[data-status="danger"]` on `.kpi__icon` - Status color tinting
### CSS Variables
- `--kpi-chart-fade` - Edge fade width for the sparkline mask (default: `10%`)
## API Reference
### KPI
The root component. Wraps Namespace UIKit [Card](https://namespace.com/docs/react/components/card).
| Prop | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------ |
| `children` | `ReactNode` | - | KPI sub-components |
Also supports all [Namespace UIKit Card](https://namespace.com/docs/react/components/card) props.
### KPI.Header
Top row container for icon, title, and actions.
| Prop | Type | Default | Description |
| ---------- | ----------- | ------- | --------------------------------- |
| `children` | `ReactNode` | - | Icon, Title, and Actions elements |
Also supports all native `div` HTML attributes.
### KPI.Content
Grid layout container placing value and trend side by side.
| Prop | Type | Default | Description |
| ---------- | ----------- | ------- | ---------------------------- |
| `children` | `ReactNode` | - | Value, Trend, Progress, etc. |
Also supports all native `div` HTML attributes.
### KPI.Icon
Status-tinted icon container.
| Prop | Type | Default | Description |
| ---------- | ------------------------------------ | ------- | ---------------------------------------- |
| `status` | `'success' \| 'warning' \| 'danger'` | - | Status color for icon background tinting |
| `children` | `ReactNode` | - | Icon element |
Also supports all native `div` HTML attributes.
### KPI.Title
Metric label rendered as a `dt` element.
| Prop | Type | Default | Description |
| ---------- | ----------- | ------- | ----------- |
| `children` | `ReactNode` | - | Title text |
Also supports all native `dt` HTML attributes.
### KPI.Value
Large formatted number display. Wraps [NumberValue](#numbervalue) with a `dd` element for semantics.
| Prop | Type | Default | Description |
| ---------- | ------------------------------------ | ------- | ------------------------------------------------------- |
| `value` | `number` | - | **Required.** The numeric value to format |
| `children` | `((formatted: string) => ReactNode)` | - | Optional render function receiving the formatted string |
Also supports all NumberValue props except `children`.
### KPI.Trend
Inline trend badge. Wraps [TrendChip](#trendchip).
Also supports all TrendChip props.
### KPI.Progress
Full-width progress bar.
| Prop | Type | Default | Description |
| -------- | ------------------------------------ | ----------- | ------------------------------------------ |
| `value` | `number` | - | **Required.** Progress value from 0 to 100 |
| `status` | `'success' \| 'warning' \| 'danger'` | `'success'` | Status color for the progress bar |
Also supports all native `div` HTML attributes.
### KPI.Actions
Action button (three-dot icon by default). Wraps Namespace UIKit [Button](https://namespace.com/docs/react/components/button) as a ghost icon-only button.
| Prop | Type | Default | Description |
| ---------- | ----------- | ------- | ------------------------------------------------ |
| `children` | `ReactNode` | - | Custom icon replacing the default three-dot icon |
Also supports all [Namespace UIKit Button](https://namespace.com/docs/react/components/button) props.
### KPI.Chart
Sparkline area chart using [Recharts](https://recharts.github.io/en-US/api/AreaChart/).
| Prop | Type | Default | Description |
| ------------- | ------------------------------------ | ---------------- | -------------------------------------------------------------------- |
| `data` | `Record
{items.map(({ color, dashed, label }) => (
);
}
function TrafficAxes({ currency = false }: { currency?: boolean }) {
return (
<>
{label}
))}
{kpis.map((kpi) => (
);
```
## Multi Line Chart Colors
{/* DEMO line-chart-multi-line-chart-colors */}
```tsx
"use client";
import { LineChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
const trafficData = [
{ month: "Jan", organic: 2000, paidAds: 1000 },
{ month: "Feb", organic: 15000, paidAds: 10000 },
{ month: "Mar", organic: 8000, paidAds: 12000 },
{ month: "Apr", organic: 14000, paidAds: 14000 },
{ month: "May", organic: 15000, paidAds: 8000 },
{ month: "Jun", organic: 8000, paidAds: 9000 },
{ month: "Jul", organic: 18000, paidAds: 12000 },
{ month: "Aug", organic: 18000, paidAds: 10000 },
{ month: "Sep", organic: 20000, paidAds: 5000 },
{ month: "Oct", organic: 17000, paidAds: 12000 },
{ month: "Nov", organic: 22000, paidAds: 18000 },
{ month: "Dec", organic: 15000, paidAds: 9000 },
];
function Legend({
items,
}: {
items: ReadonlyArray<{ color: string; dashed?: boolean; label: string }>;
}) {
return (
{kpi.label === "Total Revenue" ? (
{items.map(({ color, dashed, label }) => (
);
}
function TrafficAxes({ currency = false }: { currency?: boolean }) {
return (
<>
{label}
))}
Total balance
{current.balance}
{current.change}
{[
{ color: "var(--color-success)", data: sparkUp, label: "Revenue" },
{ color: "var(--color-danger)", data: sparkDown, label: "Churn" },
{ color: "var(--chart-3)", data: sparkUp, label: "Users" },
].map((item) => (
);
```
## Stats With Chart
{/* DEMO line-chart-stats-with-chart */}
```tsx
"use client";
import { LineChart } from "@thenamespace/uikit";
import { Card } from "@thenamespace/uikit/card";
import { Chip } from "@thenamespace/uikit/chip";
import { ArrowDown02Icon, ArrowUp02Icon, Icon } from "@thenamespace/uikit/icons";
const revenueData = [4200, 5800, 4900, 7200, 6100, 8400, 7800, 9200, 8600, 10200, 9800, 11500].map(
(revenue, index) => ({
month:
["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"][index] ??
"Unknown",
revenue,
}),
);
function Legend({
items,
}: {
items: ReadonlyArray<{ color: string; dashed?: boolean; label: string }>;
}) {
return (
{item.label}
))}
{items.map(({ color, dashed, label }) => (
);
}
function TrafficAxes({ currency = false }: { currency?: boolean }) {
return (
<>
{label}
))}
{stats.map((stat) => (
{items.map(({ color, dashed, label }) => (
);
}
export const DemoTrafficSourceExample = () => (
{label}
))}
231,856
Sessions
{items.map(({ color, dashed, label }) => (
);
}
function TrafficAxes({ currency = false }: { currency?: boolean }) {
return (
<>
{label}
))}
Total
{total.toLocaleString()}
External link
);
}
```
### Icon Placement
```tsx
import {Link} from "@thenamespace/uikit";
export function LinkIconPlacement() {
return (
Icon at end (default)
);
}
```
### Text Decoration with Tailwind CSS
Link is underlined on hover by default. Use Tailwind CSS text-decoration utilities to make the underline always visible, remove it entirely, or customize its color, style, thickness, and offset.
```tsx
import {Link} from "@thenamespace/uikit";
export function LinkUnderlineAndOffset() {
return (
Default hover underline Hover to see the underlineAlways visible underline Underline always visibleNo underline Link without any underlineChanging the underline offset
Offset 1 (1px space)
Selected: {selectedItems.length > 0 ? selectedItems.join(", ") : "None"}
{label}
{selectionMode !== "none" ? (
{selected === "all"
? "All selected"
: selected.size
? `${selected.size} selected`
: "None selected"}
) : null}
28 visitors online
Estimated arrival
{eta} min
{zone.name}
{zone.volume}
))}
Low
High
6
Routes
1.1k
Seats
94%
Peak
{flights.slice(0, 3).map((flight) => (
{flight.route}
{flight.load}
))}
{incidents.length}
Open
{critical}
Critical
{warning}
Warning
{(["critical", "warning", "info"] as const).map((severity) => (
{severity}
{
incidents.filter(
(incident) => incident.severity === severity,
).length
}
))}
6
Teams
18k
Guests
94%
Flow
{eventStations.slice(0, 4).map((station) => (
))}
A beautiful, fast, and modern React UI library for building accessible and customizable web applications with ease.
{placements.map((placement) => (
);
}
```
### Backdrop Variants
```tsx
"use client";
import { Button, Modal } from "@thenamespace/uikit";
import { Rocket01Icon, HugeiconsIcon } from "@thenamespace/uikit/icons";
export function BackdropVariants() {
const variants = ["opaque", "blur", "transparent"] as const;
return (
This modal uses the
{variants.map((variant) => (
);
}
```
### Sizes
```tsx
"use client";
import { Button, Modal } from "@thenamespace/uikit";
import { Rocket01Icon, HugeiconsIcon } from "@thenamespace/uikit/icons";
export function Sizes() {
const sizes = ["xs", "sm", "md", "lg", "cover", "full"] as const;
return (
This modal uses the
{sizes.map((size) => (
);
}
```
### Custom Backdrop
```tsx
"use client";
import { Button, Modal } from "@thenamespace/uikit";
import { SparklesIcon, HugeiconsIcon } from "@thenamespace/uikit/icons";
export function CustomBackdrop() {
return (
{size === "cover" ? (
<>
This modal uses the This backdrop features a sophisticated gradient that transitions from a dark color at the bottom to complete transparency at the top, combined with a smooth blur effect. The gradient automatically adapts its intensity for optimal contrast in both light and dark modes. isDismissable
Controls whether the modal can be dismissed by clicking the overlay
backdrop. Defaults to Clicking the backdrop won't close this modal Try clicking outside this modal on the overlay - it won't close. You must use the close button or press ESC to dismiss it. isKeyboardDismissDisabled
Controls whether the ESC key can dismiss the modal. When set to{" "}
ESC key is disabled Press ESC - nothing happens. You must use the close button or click the overlay backdrop to dismiss this modal. Using slot="close"
The simplest way to close a modal. Add
Click either button below - both have{" "}
Using Dialog render props
Access the
The buttons below use the Compare scroll behaviors - inside keeps content scrollable within the modal, outside allows page scrolling Paragraph {i + 1}: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. ))}With React.useState()
Control the modal using React's{" "}
Status:{" "} {isOpen ? "open" : "closed"}
This modal is controlled by React's With useOverlayState()
Use the Status:{" "} {state.isOpen ? "open" : "closed"}
The Fill out the form below and we'll get back to you. The modal adapts automatically when the keyboard appears on mobile. Settings Manage your preferences
Use
{animations.map(({ classNames, description, icon, name }) => {
const iconData = iconMap[icon];
return (
);
}
```
### Custom Portal
```tsx
"use client";
import {Button, Modal} from "@thenamespace/uikit";
import {useCallback, useRef, useState} from "react";
export function CustomPortal() {
const portalRef = useRef{description}
Render modals inside a custom container instead of
Apply
{!!portalContainer && (
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. This modal has custom styling applied via Tailwind classes Selected: {states.find((state) => state.id === value)?.name || "None"}
{(["primary", "secondary"] as const).map((variant) => (
);
```
## With Description
{/* DEMO native-select-with-description */}
```tsx
"use client";
import { NativeSelect } from "@thenamespace/uikit";
import { Description } from "@thenamespace/uikit/description";
import { Label } from "@thenamespace/uikit/label";
const statuses = [
["", "Select status"],
["todo", "Todo"],
["in-progress", "In Progress"],
["done", "Done"],
["cancelled", "Cancelled"],
];
function StatusOptions() {
return statuses.map(([value, label]) => (
{variant}
))}
N
{compact ? null : Namespace}
);
const User = () => (
N
{compact ? null : Namespace}
);
const User = () => (
Est. costs
$71.96
N
{compact ? null : Namespace}
);
const User = () => (
N
{compact ? null : Namespace}
);
const User = () => (
Team workspaceResponsive mobile navigation overlay.
N
{compact ? null : Namespace}
);
const User = () => (
{Array.from({ length: 20 }, (_, i) => (
Scroll down to hide the navbar, scroll up to reveal it. This is
paragraph {i + 1}.
))}
|
|---|