Once UI Core

https://github.com/once-ui-system/core
Admin
The official Once UI package and its internal development sandbox for testing, development, and...
Tokens:279,866
Snippets:2,394
Trust Score:7.4
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install and run dev environment

Source: https://github.com/once-ui-system/core/blob/main/CONTRIBUTING.md

Installs dependencies and starts the dev environment. Boots the docs app at http://localhost:3000 and the dev sandbox at http://localhost:3001 in parallel via Turborepo.

```bash
pnpm install
pnpm dev
```

--------------------------------

### Clone, install, and run development servers

Source: https://github.com/once-ui-system/core/blob/main/README.md

Clones the repository, installs dependencies with pnpm, and starts the development servers. The postinstall hook builds the core library automatically.

```bash
git clone https://github.com/once-ui-system/core.git
cd core
pnpm install
pnpm dev
```

--------------------------------

### Install and build all workspaces

Source: https://github.com/once-ui-system/core/blob/main/ARCHITECTURE.md

Installs all workspaces and builds the core via postinstall, then rebuilds everything via Turbo.

```bash
pnpm install          # installs all workspaces + builds core via postinstall
```

```bash
pnpm build            # rebuild everything via Turbo
```

--------------------------------

### Install @once-ui-system/core via npm

Source: https://github.com/once-ui-system/core/blob/main/README.md

Installs the @once-ui-system/core package via npm.

```bash
npm install @once-ui-system/core
```

--------------------------------

### Install Once UI Core 2.0

Source: https://github.com/once-ui-system/core/blob/main/MIGRATING.md

Install the latest major version of the core package. The build will not work until the migration steps are completed.

```bash
npm install @once-ui-system/core@2
```

--------------------------------

### Advanced setup with breakpoints (Providers.tsx)

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/contexts/layoutProvider.mdx

Pass a breakpoint object to LayoutProvider. This example shows a full provider stack with ThemeProvider, DataThemeProvider, ToastProvider, and IconProvider.

```tsx
import { IconProvider, ToastProvider, ThemeProvider, DataThemeProvider, LayoutProvider } from "@once-ui-system/core";

export function Providers({ children }: {
    children: React.ReactNode
}) {
    return (
      <LayoutProvider
        breakpoints={{
          s: 640,
          m: 1024,
          l: 1200,
        }}
      >
        <ThemeProvider>
          <DataThemeProvider>
            <ToastProvider>
              <IconProvider>
                {children}
              </IconProvider>
            </ToastProvider>
          </DataThemeProvider>
        </ThemeProvider>
      </LayoutProvider>
    );
}
```

--------------------------------

### Install and initialize Once UI agent harness

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/ai-coding.mdx

Install the core package and initialize the agent harness with a one-time command that writes AGENTS.md and a Cursor rule. The TypeScript block is conceptual, listing the harness files to read in your agent environment.

```bash
npm install @once-ui-system/core
npx once-ui-init-agent   # writes AGENTS.md + Cursor rule in your app (one-time)
```

```tsx
// Conceptual — read in your agent environment
// @once-ui-system/core/ai/manifest.json
// @once-ui-system/core/ai/rules.compact.md
// @once-ui-system/core/ai/tasks/pricing.json
// @once-ui-system/core/ai/components/Grid.json
```

--------------------------------

### Install Once UI Starter with npx

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/public/llms.txt

Command to scaffold a new Once UI project using the starter template.

```bash
npx create-once-ui-app@latest my-app
```

--------------------------------

### DialogProvider Setup for Stacked Dialogs

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/dialog.mdx

Wrap your app or dialog subtree in DialogProvider to enable stacked dialogs to coordinate focus and inert behavior on the base dialog. This is a required setup for the stacked dialogs example.

```tsx
import { DialogProvider } from '@once-ui-system/core';

export default function Layout({ children }) {
  return <DialogProvider>{children}</DialogProvider>;
}
```

--------------------------------

### Responsive Flex example output

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/hooks/useResponsiveClasses.mdx

Example of a Flex component with responsive props. The hook applies 'flex-column' on medium screens and 'flex-row' on large+ screens.

```tsx
<Flex direction="row" m={{ direction: 'column' }}>
  {/* Hook applies 'flex-column' on medium screens */}
  {/* Hook applies 'flex-row' on large+ screens */}
</Flex>
```

--------------------------------

### Run documentation site

Source: https://github.com/once-ui-system/core/blob/main/ARCHITECTURE.md

Starts the development server for the apps/docs documentation site on port 3000.

```bash
cd apps/docs && pnpm dev   # http://localhost:3000
```

--------------------------------

### Simple ToastProvider setup in layout.tsx

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/contexts/toastProvider.mdx

Wrap your app with ToastProvider to activate toast functionality. This is the minimal setup required to use useToast.

```tsx
<ToastProvider>
    {children}
</ToastProvider>
```

--------------------------------

### Run development sandbox

Source: https://github.com/once-ui-system/core/blob/main/ARCHITECTURE.md

Starts the development server for the apps/dev sandbox on port 3001.

```bash
cd apps/dev && pnpm dev   # http://localhost:3001
```

--------------------------------

### Advanced setup with Providers.tsx and once-ui.config.js

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/contexts/dataThemeProvider.mdx

Advanced setup: create a single source of truth for style configuration in once-ui.config.js and use a Providers component to wrap your app. The Providers.tsx file imports dataStyle from the config and passes its values to DataThemeProvider, while once-ui.config.js exports the dataStyle object with the same shape as the props.

```tsx
import { dataStyle } from "@/resources/once-ui.config";
import { DataThemeProvider, ThemeProvider, IconProvider, ToastProvider } from "@once-ui-system/core";
import { ChartVariant, ChartMode } from "@once-ui-system/core/data";

export function Providers({ children }: {
    children: React.ReactNode
}) {
    return (
      <ThemeProvider>
        <DataThemeProvider
          variant={dataStyle.variant as ChartVariant}
          mode={dataStyle.mode as ChartMode}
          height={dataStyle.height}
          axis={{
            stroke: dataStyle.axis.stroke
          }}
          tick={{
            fill: dataStyle.tick.fill,
            fontSize: dataStyle.tick.fontSize,
            line: dataStyle.tick.line
          }}>
          <ToastProvider>
            <IconProvider>
              {children}
            </IconProvider>
          </ToastProvider>
        </DataThemeProvider>
      </ThemeProvider>
    );
}
```

```tsx
export const dataStyle = {
    variant: "gradient", // flat | gradient | outline
    mode: "categorical", // categorical | divergent | sequential
    height: 24, // default chart height
    axis: {
      stroke: "var(--neutral-alpha-weak)",
    },
    tick: {
      fill: "var(--neutral-on-background-weak)",
      fontSize: 11,
      line: false
    },
};
```

--------------------------------

### Initialize agent with npx once-ui-init-agent

Source: https://github.com/once-ui-system/core/blob/main/packages/core/AGENTS.md

One-time project setup command that writes AGENTS.md and a Cursor rule in the consumer app.

```bash
# One-time project setup (writes AGENTS.md + Cursor rule in consumer app)
npx once-ui-init-agent
```

--------------------------------

### Advanced IconProvider setup with Providers.tsx and icons.ts

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/contexts/iconProvider.mdx

Advanced setup: create a separate icons.ts file and a Providers component. The Providers component wraps the app with ThemeProvider, DataThemeProvider, ToastProvider, and IconProvider. The icons.ts file defines an iconLibrary object and augments the IconLibraryOverrides interface so that <Icon name="..." /> type-checks.

```tsx
import { iconLibrary } from "../resources/icons.ts";
import { IconProvider, ToastProvider, ThemeProvider, DataThemeProvider } from "@once-ui-system/core";

export function Providers({ children }: {
    children: React.ReactNode
}) {
    return (
      <ThemeProvider>
        <DataThemeProvider>
          <ToastProvider>
            <IconProvider icons={iconLibrary}>
              {children}
            </IconProvider>
          </ToastProvider>
        </DataThemeProvider>
      </ThemeProvider>
    );
}
```

```tsx
// Your own icons, merged with the ones Once UI ships
import {
    HiChevronUp,
    HiChevronDown,
    HiChevronRight,
    HiChevronLeft,
    HiOutlineArrowPath,
    HiOutlineSun,
    HiOutlineMoon,
    HiOutlineEye,
    HiOutlineEyeSlash,
    HiOutlineClipboard,
    HiOutlineMagnifyingGlass,
    HiOutlineLink,
    HiArrowUpRight,
    HiOutlineShieldCheck,
    HiOutlineSparkles,
    HiOutlineComputerDesktop,
    HiOutlineQuestionMarkCircle,
    HiOutlineInformationCircle,
    HiOutlineExclamationTriangle,
    HiOutlineExclamationCircle,
    HiOutlineCheckCircle,
    HiOutlineXMark,
    HiOutlineUser,
    HiOutlineEyeDropper,
    HiOutlineMinus,
    HiOutlinePlus,
    HiOutlineCalendar,
    HiOutlineDocumentDuplicate,
    HiOutlineCheck,
    HiOutlineArrowsPointingIn,
    HiOutlineArrowsPointingOut,
} from "react-icons/hi2";

export const iconLibrary = {
    chevronUp: HiChevronUp,
    chevronDown: HiChevronDown,
    chevronRight: HiChevronRight,
    chevronLeft: HiChevronLeft,
    refresh: HiOutlineArrowPath,
    light: HiOutlineSun,
    dark: HiOutlineMoon,
    help: HiOutlineQuestionMarkCircle,
    info: HiOutlineInformationCircle,
    warning: HiOutlineExclamationTriangle,
    danger: HiOutlineExclamationCircle,
    checkbox: HiOutlineCheck,
    check: HiOutlineCheckCircle,
    copy: HiOutlineDocumentDuplicate,
    eyeDropper: HiOutlineEyeDropper,
    clipboard: HiOutlineClipboard,
    person: HiOutlineUser,
    close: HiOutlineXMark,
    openLink: HiOutlineLink,
    arrowUpRight: HiArrowUpRight,
    minus: HiOutlineMinus,
    plus: HiOutlinePlus,
    calendar: HiOutlineCalendar,
    eye: HiOutlineEye,
    eyeOff: HiOutlineEyeSlash,
    search: HiOutlineMagnifyingGlass,
    security: HiOutlineShieldCheck,
    sparkle: HiOutlineSparkles,
    computer: HiOutlineComputerDesktop,
    minimize: HiOutlineArrowsPointingIn,
    maximize: HiOutlineArrowsPointingOut,
};

// Teach Once UI these names, so <Icon name="chevronUp" /> type-checks.
// Derived from the object above, so the two cannot drift apart.
declare module "@once-ui-system/core" {
  interface IconLibraryOverrides extends Record<keyof typeof iconLibrary, true> {}
}
```

--------------------------------

### Monorepo pnpm scripts for dev, build, start, lint, format, typecheck, test, and clean

Source: https://github.com/once-ui-system/core/blob/main/AGENTS.md

Standard pnpm scripts for the monorepo. pnpm dev runs all dev servers in parallel (docs on :3000, dev on :3001, core watch). pnpm build builds everything, pnpm start starts all built apps, and pnpm lint runs Biome via Turbo.

```bash
pnpm dev
```

```bash
pnpm dev:core
```

```bash
pnpm dev:docs
```

```bash
pnpm dev:dev
```

```bash
pnpm build
```

```bash
pnpm build:core
```

```bash
pnpm build:docs
```

```bash
pnpm build:dev
```

```bash
pnpm start
```

```bash
pnpm start:docs
```

```bash
pnpm start:dev
```

```bash
pnpm lint
```

```bash
pnpm format
```

```bash
pnpm typecheck
```

```bash
pnpm test
```

```bash
pnpm clean
```

--------------------------------

### Spacing tokens usage example

Source: https://github.com/once-ui-system/core/blob/main/packages/core/ai/rules.md

Shows the recommended way to use spacing tokens via props like gap and padding, versus raw CSS in a style object. The good example uses Column with gap="8" and padding="24"; the bad example uses a div with inline style.

```tsx
// Good
<Column gap="8" padding="24">
// Bad
<div style={{ gap: 8, padding: 24 }}>
```

--------------------------------

### Import manifest from package

Source: https://github.com/once-ui-system/core/blob/main/packages/core/AGENTS.md

Import the manifest JSON using a readable path that is version-pinned to your install.

```tsx
// Readable paths (version-pinned to your install)
import manifest from '@once-ui-system/core/ai/manifest.json';
```

--------------------------------

### useStyle Overrides Example (tsx)

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/contexts/themeProvider.mdx

Shows how to use data-theme and data-border attributes to override styles in a Column and Row layout. The example includes a dark theme with playful border for the Column, and a light theme with rounded border for the Row.

```tsx
<Column
    data-theme="dark"
    data-border="playful">
    <Row
      data-theme="light"
      data-border="rounded">
      {children}
    </Row>
    <Row>
      {children}
    </Row>
</Column>
```

--------------------------------

### RevealFx

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/effects/revealFx.mdx

Documentation for the RevealFx component, including usage example and prop reference.

```APIDOC
## RevealFx

### Description
Animates content into view using a vertical translateY motion. You can control the speed, delay, and triggering behavior.

### Usage
```tsx
<RevealFx>
    The revolution begins
</RevealFx>
<RevealFx delay={200} translateY={0.5}>
    Get ready for the next phase.
</RevealFx>
<RevealFx delay={400} translateY={1}>
    <Button>
      Join now
    </Button>
</RevealFx>
```

### Props
- **children** (ReactNode) - What is revealed.
- **revealed** (boolean) - Whether it has played. Latch this off useInViewport for a below-the-fold reveal.
- **revealedByDefault** (boolean) - Start revealed, for content that is already on screen.
- **speed** (string | number) - Named duration, or a number of milliseconds.
- **delay** (number) - Milliseconds before it starts. Stagger a set with index * 100.
- **translateY** (number | string) - How far it travels. A number is rem, a token is a spacing step.
- **className** (string) - Additional CSS class names.
- **style** (CSSProperties) - Inline styles.
```

--------------------------------

### HoloFx Component

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/effects/holoFx.mdx

Documentation for the HoloFx component, including its props and usage example.

```APIDOC
## HoloFx Component

### Description
A lighting and texture effect that simulates a holographic sheen. It layers interactive visual effects like shine, burn, and texture over any content block, using radial masks and mouse tracking to shift light and create movement. Not supported on touch-screens.

### Props

#### HoloFx Props
- **children** - The content to apply the effect to.
- **className** - Additional CSS class names.
- **style** - Inline styles.
- **shine** - The specular highlight layer. See Shine Props below.
- **burn** - The blown-out highlight layer. See Burn Props below.
- **texture** - The overlaid texture layer. See Texture Props below.

#### Shine Props
- **opacity** (number) - Default: `30` - Opacity of the shine layer.
- **filter** (string) - Default: `-` - CSS filter applied to the shine layer.
- **blending** (mixBlendMode) - Default: `color-dodge` - Blend mode for the shine layer.
- **mask** (MaskOptions) - Default: `-` - Mask options for the shine layer.

#### Burn Props
- **opacity** (number) - Default: `30` - Opacity of the burn layer.
- **filter** (string) - Default: `brightness(0.2) contrast(2)` - CSS filter applied to the burn layer.
- **blending** (mixBlendMode) - Default: `color-dodge` - Blend mode for the burn layer.
- **mask** (MaskOptions) - Default: `-` - Mask options for the burn layer.

#### Texture Props
- **opacity** (number) - Default: `10` - Opacity of the texture layer.
- **filter** (string) - Default: `-` - CSS filter applied to the texture layer.
- **blending** (mixBlendMode) - Default: `color-dodge` - Blend mode for the texture layer.
- **image** (string) - Default: `repeating-linear-gradient(...)` - Image or gradient used for the texture.
- **mask** (MaskOptions) - Default: `-` - Mask options for the texture layer.

#### Mask Options
- **maskPosition** (string) - Default: `100 200` - Position of the mask.

### Example
```tsx
<HoloFx
    border="brand-alpha-weak"
    maxWidth={24}
    aspectRatio={3 / 4}
    radius="l"
    shine={{
      opacity: 30,
      blending: "color-dodge",
    }}
    burn={{
      opacity: 30,
      blending: "color-dodge",
    }}
    texture={{
      opacity: 10,
      image: "/images/textures/foil.jpg",
      blending: "color-dodge",
    }}
  >
    <Media src="/images/docs/once-ui/proxima-b.jpg" />
    <Fade>
      Proxima B
    </Fade>
</HoloFx>
```

### Performance
HoloFx automatically detects low-end devices and the `prefers-reduced-motion` system setting. When either is detected, the mouse-tracking effect is paused. The effect also pauses when the element is outside the viewport. You can override this with the `reducedMotion` prop.
```

--------------------------------

### UserMenu Component

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/userMenu.mdx

Documentation for the UserMenu component, including its props and usage examples.

```APIDOC
## UserMenu Component

### Description
Renders a user avatar and name, and opens a dropdown for settings or account-level actions when clicked or focused. Built on top of `DropdownWrapper` and `User` components.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | - | The user's name to display. |
| `subline` | `ReactNode` | - | Additional text or node displayed under the name. |
| `avatarProps` | `AvatarProps` | - | Props passed to the underlying `Avatar` component. |
| `loading` | `boolean` | `false` | When `true`, shows skeleton content while loading profile data. |
| `minWidth` | `SpacingToken` | - | Minimum width of the dropdown. |
| `maxWidth` | `SpacingToken` | - | Maximum width of the dropdown. |
| `minHeight` | `SpacingToken` | - | Minimum height of the dropdown. |
| `className` | `string` | - | Additional CSS class name. |
| `style` | `CSSProperties` | - | Inline style object. |
| `selected` | `boolean` | - | Mark the trigger as active while the menu is open. |
| `placement` | `string` | - | Which side the menu opens on. |
| `dropdown` | `ReactNode` | - | The menu contents. |

### Example

```tsx
<UserMenu
  name="Lorant One"
  subline="Design Engineer"
  placement="right-end"
  avatarProps={{ src: "/images/avatar.jpg" }}
  dropdown={
    <Column gap="4" padding="4" minWidth={10}>
      <Option fillWidth prefix={<Icon size="xs" onBackground="neutral-weak" name="settings" />} label="Settings" />
      <Option fillWidth prefix={<Icon size="xs" onBackground="neutral-weak" name="logout" />} label="Log out" />
    </Column>
  }
/>
```

### Loading State

Set `loading={true}` to show skeleton content while profile data is being loaded.

```tsx
<UserMenu loading />
```
```

--------------------------------

### MatrixFx with reveal direction

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/effects/matrixFx.mdx

Control where the reveal animation starts from using the revealFrom prop. The example sets revealFrom="top" to start the animation from the top.

```tsx
<MatrixFx
    height={24}
    revealFrom="top"
    colors={["brand-solid-strong"]}
/>
```

--------------------------------

### ScrollToTop with Custom Offset

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/scrollToTop.mdx

Example showing how to set a custom scroll offset for the button to appear.

```APIDOC
## ScrollToTop with Custom Offset

### Description
Demonstrates setting a higher offset value to control when the button appears.

### Usage
```tsx
<ScrollToTop offset={500}>
    <IconButton icon="chevronUp"/>
</ScrollToTop>
```

### Props
- **offset** (number) - Optional - How far down the page before it appears, in pixels.
```

--------------------------------

### GET /api/og/generate

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/ogCard.mdx

Used in advanced setups where OG images are dynamically generated server-side. This is optional depending on your configuration.

```APIDOC
## GET /api/og/generate

### Description
Used in advanced setups where OG images are dynamically generated server-side. This is optional depending on your configuration.

### Method
GET

### Endpoint
/api/og/generate

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL for which to generate an OG image.

### Response
#### Success Response (200)
- **image** (binary) - The generated OG image.

#### Response Example
[Binary image data]
```

--------------------------------

### Button behavior examples

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/elementType.mdx

Shows how ElementType renders as a button when provided with an onClick handler or a type prop.

```tsx
// Renders as a button with onClick handler
<ElementType onClick={() => console.log('Button clicked')}>
    Perform Action
</ElementType>

// Renders as a submit button
<ElementType type="submit">
    Submit Form
</ElementType>
```

--------------------------------

### TypeFx custom trigger

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/effects/typeFx.mdx

Use this to programmatically control when the typing animation starts. Set `trigger="custom"` and use the `onTrigger` prop to receive a function that starts the animation; store it in a ref and call it from a button click. The example shows a button that triggers the typing when clicked.

```tsx
function TypeFxCustomExample() {
  const triggerFnRef = useRef<(() => void) | null>(null);

  return (
    <>
      <TypeFx
        words={["Click the button", "to start typing", "this animation"]}
        speed={60}
        hold={1500}
        trigger="custom"
        onTrigger={(fn) => {
          triggerFnRef.current = fn;
        }}
      />
      <Button onClick={() => triggerFnRef.current?.()}>
        Start typing
      </Button>
    </>
  );
}
```

--------------------------------

### API debugging with dev.log and dev.error

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/utils/devLogger.mdx

Use dev.log and dev.error to trace API calls during development. This example logs the start of a fetch, the received data, and any errors that occur.

```tsx
import { dev } from '@once-ui-system/core';

async function fetchData() {
  dev.log('Fetching data...');
  
  try {
    const response = await fetch('/api/data');
    const data = await response.json();
    dev.log('Data received:', data);
    return data;
  } catch (error) {
    dev.error('Fetch failed:', error);
    throw error;
  }
}
```

--------------------------------

### Clone Once UI Starter with git

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/public/llms.txt

Command to clone the Once UI Next.js starter repository.

```bash
git clone https://github.com/once-ui-system/nextjs-starter.git
```

--------------------------------

### CelebrationFx with trigger="hover"

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/effects/celebrationFx.mdx

Use trigger="hover" to start the celebration when the user hovers over the component. The example shows a confetti effect centered within a Text component.

```tsx
<CelebrationFx
    height={16}
    type="confetti"
    trigger="hover"
    center
>
    <Text variant="heading-strong-l">
      Hover me!
    </Text>
</CelebrationFx>
```

--------------------------------

### Basic usage with label and description props

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/timeline.mdx

Use the label and description props for quick setup. The items array includes state values like 'completed', 'active', and 'default'.

```tsx
<Timeline
    items={[
      {
        label: "January 2024",
        description: "Project kickoff",
        state: "completed"
      },
      {
        label: "October 2024",
        description: "Development in progress",
        state: "active"
      },
      {
        label: "December 2024",
        description: "Launch planned",
        state: "default"
      }
    ]}
/>
```

--------------------------------

### Button Horizontal Alignment with horizontal Prop

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/button.mdx

Control the horizontal alignment of button content using the horizontal prop with values start, center, end, and between. The example uses fillWidth and optional prefix/suffix icons.

```tsx
<Button fillWidth horizontal="start" prefixIcon="check">
    Left Aligned
  </Button>
  <Button fillWidth horizontal="center">
    Center Aligned
  </Button>
  <Button fillWidth horizontal="end" suffixIcon="chevronDown">
    Right Aligned
  </Button>
  <Button fillWidth horizontal="between" prefixIcon="check" suffixIcon="chevronDown">
    Space Between
</Button>
```

--------------------------------

### Custom threshold and rootMargin options

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/hooks/useInViewport.mdx

Customize the viewport detection by passing IntersectionObserverInit options as the second argument. The first example triggers when 50% of the element is visible, the second starts detecting 100px before the element enters.

```tsx
// Trigger when 50% of the element is visible
const isHalfVisible = useInViewport(ref, { threshold: 0.5 });

// Start detecting 100px before the element enters
const isNearViewport = useInViewport(ref, { rootMargin: "100px" });
```

--------------------------------

### onBlockChange handler with minimum length check

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/scrubber.mdx

Example of handling block edits. onBlockChange provides absolute times clamped to [0, duration] and measured from gesture start. This handler refuses changes shorter than MIN_MS and updates the block state.

```tsx
onBlockChange={(trackId, blockId, next) => {
  if (next.end - next.start < MIN_MS) return;  // refuse: nothing moves
  setBlocks((current) =>
    current.map((b) => (b.id === blockId ? { ...b, ...next } : b)),
  );
}}
```

--------------------------------

### Create a table of contents with useHeadingLinks

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/hooks/useHeadingLinks.mdx

Use this hook to get an array of heading objects and render a navigation list. The example shows a TableOfContents component that maps over the headings, using the heading level to indent items and linking to the heading ID.

```tsx
import { useHeadingLinks } from '@once-ui-system/core';

function TableOfContents() {
  const headings = useHeadingLinks();

  return (
    <nav>
      <h2>On this page</h2>
      <ul>
        {headings.map((heading) => (
          <li
            key={heading.id}
            style={{ marginLeft: (heading.level - 2) * 16 }}
          >
            <a href={'#' + heading.id}>{heading.text}</a>
          </li>
        ))}
      </ul>
    </nav>
  );
}
```

--------------------------------

### Root layout.tsx with Once UI providers and ThemeInit

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/config.mdx

Recommended root layout.tsx for Once UI. Imports global styles and tokens, sets up the html element with font variables, initializes the theme via ThemeInit with design settings, and wraps children in the required providers (LayoutProvider, ThemeProvider, DataThemeProvider, ToastProvider, IconProvider).

```tsx
import '@once-ui-system/foundations/css/styles.css';
import '@once-ui-system/foundations/css/tokens.css';

import classNames from "classnames";
import { Column, ThemeInit } from "@once-ui-system/core";
import { fonts } from "../resources/once-ui.config";

interface RootLayoutProps {
    children: React.ReactNode;
}

export default async function RootLayout({ children }: RootLayoutProps) {
    return (
      <>
        <Column
          as="html"
          lang="en"
          suppressHydrationWarning
          className={classNames(
            fonts.primary.variable,
            fonts.secondary.variable,
            fonts.tertiary.variable,
            fonts.code.variable,
          )}
        >
          <head>
            <ThemeInit
              config={{
                theme: "system",
                brand: "blue",
                accent: "indigo",
                neutral: "gray",
                solid: "contrast",
                'solid-style': "flat",
                border: "playful",
                surface: "filled",
                transition: "all",
                scaling: "100",
                'viz-style': "gradient",
              }}
            />
          </head>
          <LayoutProvider>
            <ThemeProvider>
              <DataThemeProvider>
                <ToastProvider>
                  <IconProvider>
                    <Column background="page" as="body" fillWidth margin="0" padding="0" style={{ minHeight: "100vh" }}>
                      {children}
                    </Column>
                  </IconProvider>
                </ToastProvider>
              </DataThemeProvider>
            </ThemeProvider>
          </LayoutProvider>
        </Column>
      </>
    );
}
```

--------------------------------

### Available methods: log, warn, error, info, debug

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/utils/devLogger.mdx

All standard console methods are available on the dev logger. This example demonstrates log, warn, error, info, and debug calls with typical arguments.

```tsx
import { dev } from '@once-ui-system/core';

// General logging
dev.log('Debug message', { data: 'value' });

// Warnings
dev.warn('Something might be wrong');

// Errors
dev.error('An error occurred', error);

// Info
dev.info('Informational message');

// Debug
dev.debug('Detailed debug info');
```

--------------------------------

### Stack gradient, lines, and dots on a Background

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/background.mdx

Combine gradient, lines, and dots props on the Background component to stack multiple background effects. The example sets each effect's display to true, with opacity 1, and uses accent-background-strong for the gradient start and lines, static-transparent for the gradient end, and page-background for the dots.

```tsx
<Background
    fill
    height={16}
    gradient={{ 
      display: true, 
      opacity: 1,
      x: 50,
      y: 0,
      colorStart: "accent-background-strong",
      colorEnd: "static-transparent"
    }}
    lines={{
      display: true,
      opacity: 1,
      size: "16",
      thickness: 1,
      angle: 90,
      color: "accent-background-strong"
    }}
    dots={{
      display: true,
      opacity: 1,
      size: "4",
      color: "page-background"
    }}
/>
```

--------------------------------

### Initialize AI agent with once-ui-init-agent

Source: https://github.com/once-ui-system/core/blob/main/packages/core/README.md

Run this command once in your app to set up the AI codegen harness. It writes the project's AGENTS.md file and a Cursor rule.

```bash
npx once-ui-init-agent
```

--------------------------------

### Entry point manifest paths

Source: https://github.com/once-ui-system/core/blob/main/packages/core/AGENTS.md

Two paths to the agent harness manifest: a package path and a disk path.

```text
@once-ui-system/core/ai/manifest.json
```

```text
node_modules/@once-ui-system/core/ai/manifest.json
```

--------------------------------

### AvatarGroup size example

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/avatarGroup.mdx

Example showing the size prop with value "s". The preview demonstrates all sizes (xs, s, m, l, xl) but the code example only shows size="s".

```tsx
<AvatarGroup
    size="s"
    avatars={[
      { value: "A" },
      { value: "B" },
      { value: "C" },
      { value: "D" }
    ]}
/>
```

--------------------------------

### OTPInput with onComplete and autoFocus

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/form-controls/otpInput.mdx

Use this example to render an OTP input with six boxes. It calls onComplete with the full code when the last box is filled, and shows a success toast with the submitted code. The autoFocus prop focuses the first box on mount.

```tsx
const { addToast } = useToast();

const handleComplete = (code: string) => {
    addToast({ variant: "success", message: "Submitted " + code });
};

<OTPInput
    id="verification-code"
    length={6}
    onComplete={handleComplete}
    autoFocus
/>
```

--------------------------------

### Fade as edge overlay strip example

Source: https://github.com/once-ui-system/core/blob/main/packages/core/ai/rules.md

Fade is an edge overlay strip for scroll-fade, not a content wrapper. The good example shows a thin absolute strip over the scroll edge; the bad example wraps content incorrectly.

```tsx
// Good: thin absolute strip over the scroll edge
<Column flex={1} overflowY="auto">...</Column>
<Fade position="absolute" top="0" left="0" fillWidth height="40" to="bottom" base="surface" pointerEvents="none" />
// Bad
<Fade to="top" fill><Column overflowY="auto">...</Column></Fade>

```

--------------------------------

### Text prop vs children duplication example

Source: https://github.com/once-ui-system/core/blob/main/packages/core/ai/rules.md

Components with a text prop render it; passing the same text as both prop and children causes duplication. The good examples show correct usage, the bad example shows the duplicate rendering.

```tsx
// Good
<Badge>{unread}</Badge>  or  <Tag size="s">Save 20%</Tag>
// Bad: renders "2 unread2" / "Save 20%Save 20%"
<Badge title={`${unread} unread`}>{unread}</Badge>
<Tag label="Save 20%">Save 20%</Tag>

```

--------------------------------

### Kbar inputSize prop examples

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/modules/kbar.mdx

Demonstrates the inputSize prop with three sizes: m, s, and l. Each Kbar uses the same items array and a Button trigger.

```tsx
const items = [
    { id: 'home', name: 'Home', section: 'Navigation', keywords: 'home', href: '/' },
];

<Kbar inputSize="m" items={items}>
    <Button>Open</Button>
</Kbar>

<Kbar inputSize="s" items={items}>
    <Button>Open (small)</Button>
</Kbar>

<Kbar inputSize="l" items={items}>
    <Button>Open (large)</Button>
</Kbar>
```

--------------------------------

### Set up Node with nvm-windows on Windows

Source: https://github.com/once-ui-system/core/blob/main/CONTRIBUTING.md

For Windows, nvm-windows does not read .nvmrc, so the version must be named explicitly. Run in a fresh terminal; existing terminals and editor shells may still use the old version.

```powershell
nvm install 22
nvm use 22
node --version   # expect v22.x
```

--------------------------------

### Advanced setup: Providers.tsx and once-ui.config.js

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/contexts/themeProvider.mdx

Create a single source of truth for style configuration in a separate file (e.g., once-ui.config.js) and use a Providers component to wrap your app. The Providers component imports the style object and passes its values to ThemeProvider, which also wraps DataThemeProvider, ToastProvider, and IconProvider. If no props are passed to ThemeProvider, it falls back to defaults; if the visitor has theme preferences saved in localStorage, those are used. To force a theme, set theme on ThemeProvider as light or dark.

```tsx
import { style } from "@/resources/once-ui.config";
import { ThemeProvider, DataThemeProvider, IconProvider, BorderStyle, ToastProvider, NeutralColor, ScalingSize, Schemes, SolidStyle, SolidType, SurfaceStyle, TransitionStyle, Theme } from "@once-ui-system/core";

export function Providers({ children }: {
    children: React.ReactNode
}) {
    return (
      <ThemeProvider
        theme={style.theme as Theme}
        brand={style.brand as Schemes}
        accent={style.accent as Schemes}
        neutral={style.neutral as NeutralColor}
        solid={style.solid as SolidType}
        solidStyle={style.solidStyle as SolidStyle}
        border={style.border as BorderStyle}
        surface={style.surface as SurfaceStyle}
        transition={style.transition as TransitionStyle}
        scaling={style.scaling as ScalingSize}>
        <DataThemeProvider>
          <ToastProvider>
            <IconProvider>
              {children}
            </IconProvider>
          </ToastProvider>
        </DataThemeProvider>
      </ThemeProvider>
    );
}
```

```tsx
export const style = {
    theme: "system", // system | dark | light
    neutral: "gray", // sand | gray | slate
    brand: "blue", // blue | indigo | violet | magenta | pink | red | orange | yellow | moss | green | emerald | aqua | cyan
    accent: "indigo", // blue | indigo | violet | magenta | pink | red | orange | yellow | moss | green | emerald | aqua | cyan
    solid: "contrast", // color | contrast
    solidStyle: "flat", // flat | plastic
    border: "playful", // rounded | playful | conservative
    surface: "translucent", // filled | translucent
    transition: "all", // all | micro | macro
    scaling: "100"
};
```

--------------------------------

### useLayout hook example

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/contexts/layoutProvider.mdx

Use useLayout to read the resolved breakpoint state. It throws outside a LayoutProvider. The example shows branching on maxWidth to render a Sheet or Popover.

```tsx
const { currentBreakpoint, maxWidth } = useLayout();

// Below the m breakpoint, render the sheet instead of the popover.
return maxWidth("s") ? <Sheet {...props} /> : <Popover {...props} />;
```

--------------------------------

### Hover trigger example

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/effects/weatherFx.mdx

Use `trigger="hover"` to only emit particles when hovering over the element. The example shows two WeatherFx components with different types and colors.

```tsx
<WeatherFx
    height={16}
    type="leaves"
    trigger="hover"
    colors={["warning-solid-strong", "danger-solid-strong"]}
    intensity={40}
/>

<WeatherFx
    height={16}
    type="rain"
    trigger="hover"
    colors={["brand-solid-medium"]}
    intensity={60}
/>
```

--------------------------------

### Stacked Dialogs Example

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/dialog.mdx

Demonstrates stacking two dialogs for multi-step interactions. The base dialog uses the 'base' prop to indicate when a stacked dialog is open, and the stacked dialog uses the 'stack' prop. The DialogProvider must wrap the app for this to work.

```tsx
const [isBaseOpen, setIsBaseOpen] = useState(false);
const [isStackedOpen, setIsStackedOpen] = useState(false);

return (
    <DialogProvider>
      <Button variant="secondary" onClick={() => setIsBaseOpen(true)}>
        Open stacked dialogs
      </Button>
      
      <Dialog
        open={isBaseOpen}
        onClose={() => setIsBaseOpen(false)}
        title="Base dialog"
        base={isStackedOpen}
        footer={
          <Row gap="8">
            <Button variant="secondary" onClick={() => setIsBaseOpen(false)}>
              Close
            </Button>
            <Button onClick={() => setIsStackedOpen(true)}>
              Open stacked dialog
            </Button>
          </Row>
        }
      >
        <Text marginBottom="16">
          This is the base dialog. Click the button below to open a stacked dialog on top.
        </Text>
      </Dialog>
      
      <Dialog
        open={isStackedOpen}
        onClose={() => setIsStackedOpen(false)}
        title="Stacked dialog"
        stack
        footer={
          <Button onClick={() => setIsStackedOpen(false)}>Close stacked dialog</Button>
        }
      >
        <Text>
          This is a stacked dialog that appears on top of the base dialog.
          Notice how the base dialog is dimmed in the background.
        </Text>
      </Dialog>
    </DialogProvider>
);
```

--------------------------------

### Mask property example

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/background.mdx

Use the mask property to create a spotlight or reveal effect. This example sets a radial mask with x, y, and radius values to fade the background layer.

```tsx
<Background
		fill
		height={16}
		gradient={{ 
			display: true, 
			opacity: 1,
			x: 50,
			y: 0,
			colorStart: "accent-background-strong",
			colorEnd: "static-transparent"
		}}
		lines={{
			display: true,
			opacity: 1,
			size: "16",
			thickness: 1,
			angle: 90,
			color: "accent-background-strong"
		}}
		mask={{
			x: 50,
			y: 0,
			radius: 50
		}}
/>
```

--------------------------------

### Enable auto play with `play` prop

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/carousel.mdx

Enable auto play with the `play` prop. The example sets `auto: true`, `interval: 5000` (5 seconds), `controls: true`, and `progress: true`, while hiding the default controls and indicator.

```tsx
<Carousel
    controls={false}
    indicator={false}
    play={{auto: true, interval: 5000, controls: true, progress: true}}
    items={[
      { slide: "/images/1.jpg", alt: "Image 1" },
      { slide: "/images/2.jpg", alt: "Image 2" },
    ]}
/>
```

--------------------------------

### Domain allowlist example

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/utils/handleOGProxy.mdx

Shows how to restrict fetching to trusted hosts by passing an allowedDomains array to handleOGProxy. Only HTTPS URLs are allowed, and private IPs, localhost, and link-local addresses are blocked.

```tsx
return handleOGProxy(request, {
  allowedDomains: ['example.com', 'cdn.example.com'],
});
```

--------------------------------

### Arrow component usage examples

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/arrow.mdx

Shows two usage examples of the Arrow component: simple usage with a trigger selector and scale, and customized usage with a color prop for solid surfaces.

```tsx
<Row id="arrow-trigger-1">
    Simple usage
    <Arrow trigger="#arrow-trigger-1" scale={1} />
  </Row>
  <Row id="arrow-trigger-2">
    Customized usage
    <Arrow trigger="#arrow-trigger-2" color="onSolid" scale={1.2} />
</Row>
```

--------------------------------

### Book as a link with href

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/components/book.mdx

Pass href to make the whole book a link. It renders through ElementType, so internal routes get client-side navigation and external ones get the right rel.

```tsx
<Book
  href="/library/once-ui"
  src="/images/cover.jpg"
  alt="Once UI"
/>
```

--------------------------------

### handleOGProxy(request, options)

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/utils/handleOGProxy.mdx

API documentation for the handleOGProxy function from the @once-ui-system/core server package.

```APIDOC
## handleOGProxy(request, options)

### Description
Proxies an external image request through the server to bypass CORS restrictions, add caching, and hide the original image URL from client-side code.

### Method
GET

### Endpoint
app/api/og/proxy/route.ts

### Parameters
#### Path Parameters
- **request** (Request) - Required - The incoming Next.js request object.

#### Request Body
- **options** (OGProxyOptions) - Required - Configuration options for the proxy.
- **options.userAgent** (string) - Optional - User agent string for the fetch request. Default: 'Mozilla/5.0 (compatible; OG-Proxy/1.0)'.
- **options.cacheMaxAge** (number) - Optional - Cache duration in seconds. Default: 3600.
- **options.allowedDomains** (string[]) - Optional - When set, only these domains (and their subdomains) are permitted.

### Request Example
```tsx
import { NextRequest } from 'next/server';
import { handleOGProxy } from '@once-ui-system/core/server';

export async function GET(request: NextRequest) {
  return handleOGProxy(request, {
    userAgent: 'Mozilla/5.0 (compatible; ImageProxy/1.0)',
    cacheMaxAge: 86400,
    allowedDomains: ['example.com', 'once-ui.com'],
  });
}
```

### Response
#### Success Response (200)
- **Content-Type** (string) - Original content type of the image (e.g., image/jpeg).
- **Cache-Control** (string) - Cache control header with the configured max-age.

#### Response Example
```
// Response headers
{
  'Content-Type': 'image/jpeg',  // Original content type
  'Cache-Control': 'public, max-age=3600'
}
```
```

--------------------------------

### Set up Node with nvm on macOS/Linux

Source: https://github.com/once-ui-system/core/blob/main/CONTRIBUTING.md

For macOS/Linux, installs and uses the Node version pinned in .nvmrc (22.x) and verifies it. Run in a fresh terminal; existing terminals and editor shells may still use the old version.

```bash
nvm install && nvm use
node --version   # expect v22.x
```

--------------------------------

### useToast hook example with addToast

Source: https://github.com/once-ui-system/core/blob/main/apps/docs/src/content/contexts/toastProvider.mdx

Use the useToast() hook to display notifications from anywhere in your app. This example shows how to add toasts with different variants and an optional action button for danger and warning variants.

```tsx
"use client";

import React, { useState } from "react";
import { Button, Row, useToast } from "@once-ui-system/core";

export function ToastExample() {
    const { addToast } = useToast();
    const [count, setCount] = useState(0);

    const handleAddToast = (variant: 'success' | 'danger' | 'warning' | 'info') => {
      setCount(prev => prev + 1);
      const labels: Record<string, string> = {
        success: 'Success!',
        danger: 'Error!',
        warning: 'Warning!',
        info: 'Info',
      };
      addToast({
        variant,
        message: "Toast #" + (count + 1) + " - " + labels[variant],
        action: (variant === 'danger' || variant === 'warning') ? (
          <Button size="s" onClick={() => addToast({ variant: 'success', message: 'Retry successful!' })}>
            Retry
          </Button>
        ) : undefined,
      });
    };

    return (
      <Row gap="8" wrap>
        <Button size="s" onClick={() => handleAddToast('success')}>
          Show Success
        </Button>
        <Button size="s" variant="secondary" onClick={() => handleAddToast('danger')}>
          Show Error
        </Button>
        <Button size="s" variant="tertiary" onClick={() => handleAddToast('warning')}>
          Show Warning
        </Button>
        <Button size="s" variant="tertiary" onClick={() => handleAddToast('info')}>
          Show Info
        </Button>
      </Row>
    );

}
```
Tokens:
Raw