Once UI

https://docs.once-ui.com/
Admin
Once UI is a platform offering a suite of products and tools, such as Magic Portfolio and Magic...
Tokens:135,063
Snippets:1,602
Trust Score:9.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Kbar Component Usage Examples

Source: https://docs.once-ui.com/once-ui/modules/kbar

Examples demonstrating how to use the Kbar component with different input sizes.

```APIDOC
## Kbar Component Examples

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

<Kbar items={items}>
  <Button>Open</Button>
</Kbar>
```

### Input Size Variations

#### Small Input Size
```jsx
const items = [
  { id: 'home', name: 'Home', section: 'Navigation', keywords: 'home', href: '/' },
];

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

#### Medium Input Size (Default)
```jsx
const items = [
  { id: 'home', name: 'Home', section: 'Navigation', keywords: 'home', href: '/' },
];

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

#### Large Input Size
```jsx
const items = [
  { id: 'home', name: 'Home', section: 'Navigation', keywords: 'home', href: '/' },
];

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

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

### Install Once UI Core Package

Source: https://docs.once-ui.com/once-ui/ai-coding

Install the core Once UI package using npm. This is a prerequisite for using Once UI in your project.

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

```

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

### Launch Countdown Example

Source: https://docs.once-ui.com/once-ui/effects/countdownFx

A practical example of using CountdownFx for a launch announcement, including custom text and styling.

```APIDOC
## Launch Countdown Example

### Description
Creates a compelling launch countdown integrated with other UI components for an event announcement.

### Props
- **targetDate** (Date): The target date for the launch.
- **variant** (string): Specifies the visual style of the countdown.
- **format** (string): Defines the time format for the countdown.
- **onBackground** (string): Sets the background color for the container.

### Example
```jsx
<Column gap="16" fill center padding="32" data-solid="contrast" radius="l">
  <Heading variant="display-strong-xl" align="center">
    Launching Soon
  </Heading>
  <CountdownFx
    targetDate={new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)}
    variant="display-strong-l"
    format="DD:HH:MM:SS"
    onBackground="brand-medium"
  />
  <Text variant="body-default-m">
    Get ready for something amazing
  </Text>
</Column>
```
```

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

### Launch Countdown Example

Source: https://docs.once-ui.com/once-ui/effects/countdownFx

A complete example of a launch countdown, including a heading and descriptive text, using 'DD:HH:MM:SS' format and a brand background.

```jsx
<Column gap="16" fill center padding="32" data-solid="contrast" radius="l">
  <Heading variant="display-strong-xl" align="center">
    Launching Soon
  </Heading>
  <CountdownFx
    targetDate={new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)}
    variant="display-strong-l"
    format="DD:HH:MM:SS"
    onBackground="brand-medium"
  />
  <Text variant="body-default-m">
    Get ready for something amazing
  </Text>
</Column>
```

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

### Basic SplitView Example

Source: https://docs.once-ui.com/once-ui/components/splitView

Demonstrates a basic horizontal SplitView with default settings. Use this for standard left-right panel layouts.

```jsx
<SplitView 
  defaultSplit={0.4}
  leftPanel={
    <Column fillWidth padding="20" gap="12" border="surface" background="surface" radius="l">
      <Text variant="heading-strong-m">Left Panel</Text>
      <Text onBackground="neutral-weak">
        This is the left panel content. You can resize this panel by dragging the divider.
      </Text>
    </Column>
  }
  rightPanel={
    <Column fillWidth padding="20" gap="12" border="surface" background="surface" radius="l">
      <Text variant="heading-strong-m">Right Panel</Text>
      <Text onBackground="neutral-weak">
        This is the right panel content. The divider is draggable and provides visual feedback.
      </Text>
    </Column>
  }
/>
```

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

### OTPInput Component Example

Source: https://docs.once-ui.com/once-ui/form-controls/input

Provides an example of the OTPInput component for entering one-time passwords. It uses the useToast hook to display a success message upon completion.

```jsx
const [value, setValue] = useState<number>(0);

const handleChange = (newValue: number) => {
  setValue(newValue);
};

<NumberInput
  id="number-input-example"
  label="Quantity"
  value={value}
  onChange={handleChange}
  min={0}
  max={100}
  step={1}
/>
```

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

### Advanced ThemeProvider Setup with Configuration File

Source: https://docs.once-ui.com/once-ui/contexts/themeProvider

Centralize style configurations in a separate file (e.g., `once-ui.config.js`) and use a `Providers` component to wrap your app. This setup integrates ThemeProvider with other Once UI providers like DataThemeProvider, ToastProvider, and IconProvider.

```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>
  );
}
```

```javascript
import { style } from "@/resources/once-ui.config";

// Example configuration object (actual content may vary)
const style = {
  theme: "system",
  brand: "blue",
  accent: "indigo",
  neutral: "gray",
  solid: "contrast",
  solidStyle: "flat",
  border: "playful",
  surface: "translucent",
  transition: "all",
  scaling: "100"
};
```

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

### Simple LayoutProvider Setup

Source: https://docs.once-ui.com/once-ui/contexts/layoutProvider

Wrap your application with the LayoutProvider component to enable window size tracking for Flex and Grid components.

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

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

### Simple ToastProvider Setup

Source: https://docs.once-ui.com/once-ui/contexts/toastProvider

Wrap your application with ToastProvider to enable toast functionality globally.

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

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

### Basic AvatarGroup Example

Source: https://docs.once-ui.com/once-ui/components/avatarGroup

A basic example demonstrating how to use the AvatarGroup component with different avatar sources (image and value).

```jsx
<AvatarGroup
  size="l"
  avatars={[
    { src: "/images/avatar.jpg" },
    { value: "B" },
    { value: "C" },
    { value: "D" },
    { value: "E" }
  ]} 
/>
```

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

### Add Once UI to Existing Project

Source: https://docs.once-ui.com/once-ui/quick-start

Install the core Once UI package into an existing project using npm.

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

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

### System Monitor Component with useStreamingData

Source: https://docs.once-ui.com/once-ui/hooks/useStreamingData

Demonstrates a real-world example of using the useStreamingData hook to create a system monitoring dashboard. It initializes data, defines how to get the next target values, and displays the streaming data using a LineChart.

```tsx
function SystemMonitor() {
const { data, running, setRunning } = useStreamingData({
  initialData: Array.from({ length: 20 }, (_, i) => ({
    time: i,
    cpu: 20 + Math.random() * 10,
    memory: 40 + Math.random() * 10,
    network: 10 + Math.random() * 5
  })),
  windowSize: 30,
  intervalMs: 1000,
  xKey: 'time',
  numericKeys: ['cpu', 'memory', 'network'],
  getNextTarget: ({ lastPoint }) => {
    // Simulate realistic system metrics
    const cpuChange = (Math.random() - 0.5) * 15;
    const memoryChange = (Math.random() - 0.5) * 5;
    const networkChange = (Math.random() - 0.5) * 10;
    
    return {
      cpu: Math.min(100, Math.max(0, lastPoint.cpu + cpuChange)),
      memory: Math.min(100, Math.max(0, lastPoint.memory + memoryChange)),
      network: Math.min(100, Math.max(0, lastPoint.network + networkChange))
    };
  }
});

return (
  <Flex direction="column" gap="16">
    <Flex gap="8">
      <Button onClick={() => setRunning(!running)}>
        {running ? 'Pause' : 'Resume'}
      </Button>
      <Text>CPU: {data[data.length - 1]?.cpu.toFixed(1)}%</Text>
      <Text>Memory: {data[data.length - 1]?.memory.toFixed(1)}%</Text>
    </Flex>
    <LineChart width={800} height={300} data={data}>
      <Line dataKey="cpu" stroke="#ff4444" isAnimationActive={false} />
      <Line dataKey="memory" stroke="#44ff44" isAnimationActive={false} />
      <Line dataKey="network" stroke="#4444ff" isAnimationActive={false} />
    </LineChart>
  </Flex>
);
}
```

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

### Simple IconProvider Setup

Source: https://docs.once-ui.com/once-ui/contexts/iconProvider

Wrap your application with IconProvider and pass an object of icon instances as props. This is useful for basic integration.

```tsx
import { HiHome } from "react-icons/hi2";

<IconProvider icons={{home: HiHome}}>
  {children}
</IconProvider>
```

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

### InteractiveDetails Basic Examples

Source: https://docs.once-ui.com/once-ui/form-controls/interactiveDetails

Demonstrates the basic usage of the InteractiveDetails component with a label, a label and description, and a label with a help tooltip.

```javascript
<InteractiveDetails 
  label="Basic label" 
/>

<InteractiveDetails 
  label="With description" 
  description="This is a description for the interactive element"
/>

<InteractiveDetails 
  label="With help tooltip" 
  iconButtonProps={{ tooltip: "This is a help tooltip", tooltipPosition: "right" }}
/>
```

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

### Simple DataThemeProvider Setup

Source: https://docs.once-ui.com/once-ui/contexts/dataThemeProvider

Wrap your application with DataThemeProvider and pass style configurations directly as props for simple overrides.

```tsx
<DataThemeProvider
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
  }}

>

  {children}

</DataThemeProvider>
```

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

### Basic HeadingLink Example

Source: https://docs.once-ui.com/once-ui/modules/headingLink

Demonstrates a simple HeadingLink component used for a section heading.

```jsx
<HeadingLink as="h2" id="example-section">
  Example Section
</HeadingLink>
<Text onBackground="neutral-weak">
  This is a section with a linkable heading
</Text>
```

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

### LogoCloud with Rotation

Source: https://docs.once-ui.com/once-ui/components/logoCloud

Example demonstrating the rotation feature when the number of logos exceeds the limit.

```APIDOC
## Rotation

### Description
When the number of logos exceeds the `limit` prop, the LogoCloud component automatically rotates through them. Rotation is disabled if the limit equals the total number of logos.

### Props
* **rotationInterval** (number) - Optional - The interval in milliseconds for logo rotation. Defaults to 5000.
* **columns** (string) - Optional - Defines the number of columns in the grid. Example: "3".
* **gap** (string) - Optional - Defines the gap between grid items. Example: "16".

### Example
```jsx
<LogoCloud 
  logos={[
    { wordmark: "/trademarks/type-dark.svg", size: "m" },
    { wordmark: "/trademarks/type-dark.svg", size: "m" },
    { wordmark: "/trademarks/type-dark.svg", size: "m" },
    { wordmark: "/trademarks/type-dark.svg", size: "m" },
    { wordmark: "/trademarks/type-dark.svg", size: "m" },
    { wordmark: "/trademarks/type-dark.svg", size: "m" }
  ]}
  limit={6}
  rotationInterval={3000}
  columns="3"
  gap="16"
/>
```
```

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

### Basic MasonryGrid Usage

Source: https://docs.once-ui.com/once-ui/components/masonryGrid

Demonstrates the basic setup of the MasonryGrid component with default properties and responsive column adjustments for different screen sizes.

```jsx
<MasonryGrid
  padding="l"
  radius="l"
  background="neutral-medium"
  columns={6}
  m={{ columns: 4 }}
  s={{ columns: 2 }}
>
  {[16, 6, 4, 6, 16, 12, 7, 24, 4, 12, 6, 2, 24, 17, 12, 5, 9, 6, 20, 11].map((height, index) => (
      <Flex
          key={index}
          background="overlay"
          radius="l"
          border="neutral-alpha-medium"
          fill
          center
          height={height}
      >{index}
      </Flex>
  ))}
</MasonryGrid>
```

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

### PasswordInput Example

Source: https://docs.once-ui.com/once-ui/form-controls/input

Use PasswordInput for secure password entry. It includes a toggle to show or hide the password.

```jsx
const [password, setPassword] = useState<string>('');

const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
  setPassword(e.target.value);
};

<PasswordInput
  id="password-input-example"
  label="Password"
  value={password}
  onChange={handleChange}
  placeholder="Enter your password"
/>
```

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

### NavIcon Usage Example

Source: https://docs.once-ui.com/once-ui/components/navIcon

Demonstrates how to use the NavIcon component in a React application, including state management for toggling.

```APIDOC
## NavIcon Usage Example

### Description
This example shows a typical implementation of the NavIcon component within a navigation bar, illustrating its active and inactive states controlled by user interaction.

### Component
```jsx
"use client";

import { NavIcon, Flex, Text, Row, Column } from "@once-ui/components";
import { useState } from "react";

function NavIconToggle() {
  const [isActive, setIsActive] = useState(false);
  
  const handleClick = () => {
    setIsActive(!isActive);
  };

  return (
    <Column fillWidth>
      <Flex 
        paddingX="20" 
        paddingY="8" 
        background="surface"
        border="surface"
        radius="l" 
        horizontal="between" 
        vertical="center"
        fillWidth
      >
        {/* Assuming Logo and ToggleButton are defined elsewhere */}
        <Logo wordmark={false}/> 
        <NavIcon 
          isActive={isActive} 
          onClick={handleClick} 
          aria-label="Toggle navigation menu"
          aria-expanded={isActive}
          aria-controls="demo-nav"
        />
      </Flex>
      
      {isActive && (
        <Column 
          id="demo-nav"
          padding="16" 
          background="surface" 
          border="surface"
          radius="l" 
          marginTop="8"
          fillWidth
          gap="8"
        >
          {/* Example menu items */}
          <ToggleButton fillWidth horizontal="start" size="l">Home</ToggleButton>
          <ToggleButton fillWidth horizontal="start" size="l">Products</ToggleButton>
          <ToggleButton fillWidth horizontal="start" size="l">About</ToggleButton>
          <ToggleButton fillWidth horizontal="start" size="l">Contact</ToggleButton>
        </Column>
      )}
    </Column>
  );
}
```
```

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

### Multiple HeadingLinks Example

Source: https://docs.once-ui.com/once-ui/modules/headingLink

Shows how to use multiple HeadingLink components for nested sections and their content.

```jsx
<HeadingLink as="h2" id="first-section">
  First Section
</HeadingLink>
<Text onBackground="neutral-weak" marginBottom="16">
  Content for the first section
</Text>
<HeadingLink as="h3" id="subsection">
  Subsection
</HeadingLink>
<Text onBackground="neutral-weak">
  Content for the subsection
</Text>
```

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

### LogoCloud Basic Usage

Source: https://docs.once-ui.com/once-ui/components/logoCloud

Basic example of the LogoCloud component displaying a list of logos.

```APIDOC
## LogoCloud

### Description
Displays a collection of logos in a grid layout. Perfect for showcasing partners, clients, or integrations.

### Props
* **logos** (LogoProps[]) - Required - An array of logo objects, each with a `wordmark` (string) and `size` (string, e.g., 'm').
* **columns** (string) - Optional - Defines the number of columns in the grid. Example: "2".
* **gap** (string) - Optional - Defines the gap between grid items. Example: "16".
* **limit** (number) - Optional - The maximum number of logos to display at once. Defaults to 6.

### Example
```jsx
<LogoCloud 
  logos={[
    { wordmark: "/trademarks/type-dark.svg", size: "m" },
    { wordmark: "/trademarks/type-dark.svg", size: "m" },
    { wordmark: "/trademarks/type-dark.svg", size: "m" },
    { wordmark: "/trademarks/type-dark.svg", size: "m" },
    { wordmark: "/trademarks/type-dark.svg", size: "m" },
    { wordmark: "/trademarks/type-dark.svg", size: "m" }
  ]}
  columns="2"
  gap="16"
  limit={4}
/>
```
```

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

### Basic WeatherFx Implementation

Source: https://docs.once-ui.com/once-ui/effects/weatherFx

Demonstrates a basic setup of the WeatherFx component, overlaying it on an image. It includes properties for positioning and basic effect parameters.

```jsx
<Media
  src="/image.jpg"
  alt="Preview"
/>
<WeatherFx
  fill
  position="absolute"
  top="0"
  left="0"
  angle={-30}
  speed={2}
  colors={["static-white"]}
  type="rain"
  intensity={75}
/>
```

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

### Basic CursorCard Example

Source: https://docs.once-ui.com/once-ui/components/cursorCard

A standard CursorCard implementation with a Button as a trigger and a Card as the overlay content. Customize placement and maximum width as needed.

```jsx
<CursorCard
  placement="bottom-right"
  maxWidth={24}
  trigger={
    <Button weight="default" variant="secondary">
      See details
    </Button>
  }
  overlay={
    <Card maxWidth={24} radius="l-4" direction="column" border="neutral-alpha-medium">
      {children}
    </Card>
  }
/>
```

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

### Gradient Background

Source: https://docs.once-ui.com/once-ui/components/background

Example of creating a gradient background with specified colors and position.

```APIDOC
## Gradient Background

### Description
Create beautiful gradient backgrounds with customizable position, size, and colors.

### Props
- **fill** (boolean) - Optional - Whether the background should fill its container.
- **height** (number) - Optional - Specifies the height of the background element.
- **gradient** (GradientProps) - Required - Configuration for the gradient effect.
  - **display** (boolean) - Optional - Whether to display the gradient. Defaults to `false`.
  - **opacity** (number) - Optional - Opacity of the gradient. Defaults to `1`.
  - **x** (number) - Optional - Horizontal position of the gradient. Defaults to `50`.
  - **y** (number) - Optional - Vertical position of the gradient. Defaults to `50`.
  - **colorStart** (string) - Optional - Starting color of the gradient. Defaults to `var(--color-brand-medium)`.
  - **colorEnd** (string) - Optional - Ending color of the gradient. Defaults to `var(--color-success-medium)`.

### Example Usage
```jsx
<Background
  fill
  height={16}
  gradient={{
    display: true,
    opacity: 1,
    x: 50,
    y: 0,
    colorStart: "brand-background-strong",
    colorEnd: "accent-background-weak"
  }}
/>
```
```

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

### Default Option

Source: https://docs.once-ui.com/once-ui/components/option

A basic example of the Option component with a label and value.

```APIDOC
## Default Option

Represents a standard selectable item.

### Component

```jsx
<Option 
  label="Default option"
  value="default"
/>
```
```

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

### Basic ColorInput Example

Source: https://docs.once-ui.com/once-ui/form-controls/colorInput

Demonstrates the basic usage of the ColorInput component with a label and initial hex value. Use this for standard color selection without transparency.

```javascript
const [colorValue, setColorValue] = useState("#4287f5");

const handleColorChange = (e: React.ChangeEvent<HTMLInputElement>) => {
  setColorValue(e.target.value);
};

<ColorInput
  id="color-input-example"
  label="Brand Color"
  value={colorValue}
  onChange={handleColorChange}
/>
```

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

### Response Headers Example

Source: https://docs.once-ui.com/once-ui/utils/handleOGProxy

Illustrates the typical response headers returned by the handleOGProxy function, including Content-Type and Cache-Control.

```json
{
'Content-Type': 'image/jpeg',
'Cache-Control': 'public, max-age=3600'
}
```

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

### Basic Timeline Usage

Source: https://docs.once-ui.com/once-ui/components/timeline

Configure timeline items with label, description, and state props for a quick setup. Use 'completed', 'active', or 'default' states.

```jsx
<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"
    }
  ]} 
/>
```

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

### Skeleton Component Examples

Source: https://docs.once-ui.com/once-ui/components/skeleton

Demonstrates various configurations of the Skeleton component including different shapes, sizes, and animation delays for a staggered loading effect.

```jsx
<Skeleton shape="circle" width="l" height="l" />
<Skeleton shape="line" delay="1" width="m" height="xs" />
<Skeleton shape="line" delay="2" width="l" height="s" />
<Skeleton shape="block" delay="3" width="l" minHeight="80" />
```

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

### Dynamic Rendering Examples

Source: https://docs.once-ui.com/once-ui/components/elementType

Demonstrates how ElementType renders as different HTML elements based on props like href, onClick, or className.

```jsx
// Renders as a Next.js Link for internal navigation
<ElementType href="/about">
  Go to About
</ElementType>

// Renders as an anchor tag for external links
<ElementType href="https://example.com">
  Visit Example
</ElementType>

// Renders as a button when onClick is provided
<ElementType onClick={() => alert('Clicked!')}>
  Click Me
</ElementType>

// Renders as a div when no interactive props are provided
<ElementType className="container">
  Content
</ElementType>
```

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

### LogoCloud Grid Layout Customization

Source: https://docs.once-ui.com/once-ui/components/logoCloud

Example showing how to customize the grid layout using Grid component props.

```APIDOC
## Grid layout

### Description
The LogoCloud component extends the `Grid` component, allowing the use of all `Grid` props for layout customization.

### Props
* **columns** (string) - Optional - Defines the number of columns in the grid. Example: "4".
* **s** (object) - Optional - Responsive prop for small screens, defining grid properties like columns. Example: `{columns: 2}`.
* **gap** (string) - Optional - Defines the gap between grid items. Example: "24".

### Example
```jsx
<LogoCloud 
  logos={[
      { wordmark: "/trademarks/type-dark.svg", size: "s" },
      { wordmark: "/trademarks/type-dark.svg", size: "s" },
      { wordmark: "/trademarks/type-dark.svg", size: "s" },
      { wordmark: "/trademarks/type-dark.svg", size: "s" },
      { wordmark: "/trademarks/type-dark.svg", size: "s" },
      { wordmark: "/trademarks/type-dark.svg", size: "s" }
  ]}
  columns="4"
  s={{columns: 2}}
  gap="24"
/>
```
```

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

### Skeleton Component Usage

Source: https://docs.once-ui.com/once-ui/components/skeleton

Basic examples demonstrating the usage of the Skeleton component with different shapes, sizes, and animation delays.

```APIDOC
## Skeleton Component Usage

### Description
Demonstrates various ways to use the Skeleton component, including different shapes, sizes, and animation delays to create placeholder UIs during data loading.

### Examples

**Default Shapes:**
```jsx
<Skeleton shape="circle" width="l" height="l" />
<Skeleton shape="line" delay="1" width="m" height="xs" />
<Skeleton shape="line" delay="2" width="l" height="s" />
<Skeleton shape="block" delay="3" width="l" minHeight="80" />
```

**Shapes:**
```jsx
<Skeleton shape="line" height="xs" />
<Skeleton shape="circle" />
<Skeleton shape="block" minHeight="48" />
```

**Size:**
```jsx
<Skeleton shape="line" height="xl" width="xl" />
<Skeleton shape="line" height="l" width="l" />
<Skeleton shape="line" height="m" width="m" />
<Skeleton shape="line" height="s" width="s" />
<Skeleton shape="line" height="xs" width="xs" />
```

**Animation Delay:**
```jsx
<Skeleton shape="line" width="l" delay="1" />
<Skeleton shape="line" width="m" delay="2" />
<Skeleton shape="line" width="s" delay="3" />
```
```

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

### Create New Once UI App

Source: https://docs.once-ui.com/once-ui/quick-start

Use this command to quickly scaffold a new project with Once UI pre-configured.

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

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

### devLogger Available Methods Examples

Source: https://docs.once-ui.com/once-ui/utils/devLogger

Demonstrates the usage of various devLogger methods including log, warn, error, info, and debug with different argument types.

```typescript
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');
```

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

### Controlled SegmentedControl Example

Source: https://docs.once-ui.com/once-ui/components/segmentedControl

A detailed example of a controlled SegmentedControl, emphasizing the use of the 'selected' prop to manage the active button externally.

```jsx
<SegmentedControl
fillWidth={false}
selected="month"
buttons={[
  { value: "day", label: "Day" },
  { value: "week", label: "Week" },
  { value: "month", label: "Month" },
]}
onToggle={(value) => console.log(value)}
/>
```

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

### MatrixFx Hover Trigger Example

Source: https://docs.once-ui.com/once-ui/effects/matrixFx

Applies MatrixFx effects on hover. Dots appear progressively and reverse on mouse out. This example includes flicker and bulge.

```jsx
<Row
  fill
  center
  padding="24"
  border="neutral-alpha-weak"
  radius="l"
  overflow="hidden"
>
  <MatrixFx
    position="absolute"
    top="0"
    left="0"
    trigger="hover"
    size={2}
    spacing={2}
    flicker
    bulge={{
      duration: 3,
      intensity: 12,
      repeat: false
    }}
  />
  <Background
    fill
    position="absolute"
    left="0"
    top="0"
    x="0"
    y="0"
    gradient={{
      display: true,
      colorStart: "neutral-background-weak",
    }}
    pointerEvents="none"/>
  <Column align="center" horizontal="center" pointerEvents="none">
    <Logo dark icon="/trademarks/icon-dark.svg" />
    <Logo light icon="/trademarks/icon-light.svg" />
  </Column>
</Row>
<Row
  fill
  center
  padding="24"
  border="neutral-alpha-weak"
  radius="l"
  overflow="hidden"
>
  <MatrixFx
    position="absolute"
    top="0"
    left="0"
    trigger="hover"
    size={2}
    spacing={2}
    flicker
    revealFrom="bottom"
  />
  <Background
    fill
    position="absolute"
    left="0"
    top="0"
    x="0"
    y="0"
    gradient={{
      display: true,
      colorStart: "neutral-background-weak",
    }}
    pointerEvents="none"/>
  <Column align="center" horizontal="center" pointerEvents="none">
    <Logo dark icon="/trademarks/icon-dark.svg" />
    <Logo light icon="/trademarks/icon-light.svg" />
  </Column>
</Row>
```

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

### Basic Usage of handleOGProxy

Source: https://docs.once-ui.com/once-ui/utils/handleOGProxy

Demonstrates how to set up a basic API route using handleOGProxy to proxy external images.

```APIDOC
## GET /api/og/proxy

### Description
Proxies an external image through the server to bypass CORS restrictions.

### Method
GET

### Endpoint
/api/og/proxy

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the external image to proxy.

### Request Example
```
const imageUrl = 'https://external-site.com/image.jpg';
const proxiedUrl = `/api/og/proxy?url=${encodeURIComponent(imageUrl)}`;

<img src={proxiedUrl} alt="External image" />
```

### Response
#### Success Response (200)
Returns the binary data of the image with appropriate headers.
- **Content-Type** (string) - The content type of the original image.
- **Cache-Control** (string) - Cache control headers for the proxied image.

#### Response Example
```json
{
  "image": "binary data"
}
```

### Error Handling
- **400** : Missing URL parameter.
- **500** : Failed to fetch the image.
- **Original status** : If the external server returns an error, that status is forwarded.
```

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

### Simple ThemeProvider Setup

Source: https://docs.once-ui.com/once-ui/contexts/themeProvider

Wrap your application with ThemeProvider and configure styles using props. Available options include theme mode, brand color, accent color, neutral color, solid style, border style, surface style, transition, and scaling.

```tsx
<ThemeProvider
  theme="system" // system | dark | light
  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
  neutral="gray" // sand | gray | slate
  solid="contrast" // color | contrast
  solidStyle="flat" // flat | plastic
  border="playful" // rounded | playful | conservative
  surface="translucent" // filled | translucent
  transition="all" // all | micro | macro
  scaling="100" // 90 | 95 | 100 | 105 | 110
>
  {children}
</ThemeProvider>
```

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

### Advanced LayoutProvider Setup with Custom Breakpoints

Source: https://docs.once-ui.com/once-ui/contexts/layoutProvider

Pass a custom breakpoints object to the LayoutProvider to define specific screen size thresholds. This setup is typically used within a root providers file.

```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>
  );
}
```

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

### CodeBlock with Multiple Tabs for Different Languages

Source: https://docs.once-ui.com/once-ui/modules/codeBlock

Demonstrates displaying multiple code examples (JavaScript, HTML, CSS) within a single CodeBlock component, navigable via tabs. The copy button is disabled for this example.

```javascript
// JavaScript
const button = document.createElement('button');
button.textContent = 'Example Button';
button.classList.add('secondary');
document.body.appendChild(button);
```

```javascript
<CodeBlock
  copyButton={false}
  codes={[
    {
      language: "javascript",
      label: "JavaScript",
      code:
"// JavaScript
const button = document.createElement('button');
button.textContent = 'Example Button';
button.classList.add('secondary');
document.body.appendChild(button);",
    },
    {
      language: "html",
      label: "HTML",
      code:
"<!-- HTML -->
<button class="secondary">
  Example Button
</button>"
  },
  {
      language: "css",
      label: "CSS",
      code:
"/* CSS */
button.secondary {
  background-color: #f0f0f0;
  border: 1px solid #ccc;
  border-radius: 4px;
  padding: 8px 16px;
}"
    }
  ]}
/>
```

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

### Advanced ToastProvider Setup with Providers Component

Source: https://docs.once-ui.com/once-ui/contexts/toastProvider

Integrate ToastProvider within a Providers component for advanced setup, including breakpoint-based toast positioning. Ensure all necessary providers like ThemeProvider, DataThemeProvider, and IconProvider are included.

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

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

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

### Basic Kbar Implementation

Source: https://docs.once-ui.com/once-ui/modules/kbar

Demonstrates how to integrate the Kbar component into a layout with predefined navigation items. Ensure KbarItem objects include necessary properties like id, name, section, and either href or perform.

```javascript
const kbarItems = [
  {
    id: 'home',
    name: 'Home',
    section: 'Navigation',
    shortcut: ['H'],
    keywords: 'home main start',
    href: '/',
    icon: 'home'
  },
  {
    id: 'docs',
    name: 'Documentation',
    section: 'Navigation',
    shortcut: ['D'],
    keywords: 'docs guide help',
    href: '/docs',
    icon: 'document'
  }
];

function MyLayout({ children }) {
  return (
    <>
      <header>
        <Kbar items={kbarItems}>
          <Button prefixIcon="command">Search</Button>
        </Kbar>
      </header>
      <main>
        {children}
      </main>
    </>
  );
}
```

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

### Wordmark Only

Source: https://docs.once-ui.com/once-ui/components/logo

Example of displaying only the wordmark part of the logo.

```APIDOC
## Wordmark Only

### Description
Display only the wordmark part of the logo.

### Example
```jsx
<Logo wordmark="/trademarks/type-dark.svg" size="s" />
<Logo wordmark="/trademarks/type-dark.svg" size="l" />
```
```

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

### Icon Only

Source: https://docs.once-ui.com/once-ui/components/logo

Example of displaying only the icon part of the logo.

```APIDOC
## Icon Only

### Description
Display only the icon part of the logo.

### Example
```jsx
<Logo icon="/trademarks/icon-dark.svg" size="s" />
<Logo icon="/trademarks/icon-dark.svg" size="l" />
```
```

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

### Advanced DataThemeProvider Setup with Configuration File

Source: https://docs.once-ui.com/once-ui/contexts/dataThemeProvider

Utilize a separate configuration file (e.g., once-ui.config.js) and a Providers component for centralized style management. This approach is recommended for complex applications.

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

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>
  );
}
```

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

### Option States

Source: https://docs.once-ui.com/once-ui/components/option

Examples of different states for an Option component: selected, highlighted, and danger.

```APIDOC
## Option States

Illustrates the visual states an option can have.

### Component

```jsx
<Option 
  label="Selected option"
  value="selected"
  selected
/>

<Option 
  label="Highlighted option"
  value="highlighted"
  highlighted
/>

<Option 
  label="Danger option"
  value="danger"
  danger
/>
```
```

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

### Basic Kbd Usage

Source: https://docs.once-ui.com/once-ui/components/kbd

Demonstrates the basic usage of the Kbd component to display individual keys.

```html
<Kbd>Tab</Kbd>
<Kbd>Enter</Kbd>
<Kbd>Shift</Kbd>
<Kbd>Esc</Kbd>
```

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

### Basic Dialog Implementation

Source: https://docs.once-ui.com/once-ui/components/dialog

Demonstrates how to open and manage a simple dialog with a title, description, and custom content. Use this for displaying information or collecting simple input.

```javascript
const [isOpen, setIsOpen] = useState(false);

return (
  <>
    <Button onClick={() => setIsOpen(true)}>
      Open Dialog
    </Button>
    <Dialog
      isOpen={isOpen}
      onClose={() => setIsOpen(false)}
      title="Basic dialog"
      description="This is a simple dialog with a title and description."
    >
      <Column fillWidth gap="16" marginTop="12">
        Dialog content goes here. This area can contain any React components.
        <Row fillWidth vertical="center" gap="8">
          <Input
            id="name"
            label="Enter your name"
          />
          <Button label="Submit" onClick={() => setIsOpen(false)}/>
        </Row>
      </Column>
    </Dialog>
  </>
);

```

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

### handleOGProxy with Options

Source: https://docs.once-ui.com/once-ui/utils/handleOGProxy

Shows how to customize the behavior of handleOGProxy using options for user agent and cache duration.

```APIDOC
## GET /api/og/proxy with Options

### Description
Proxies an external image with custom cache duration and user agent settings.

### Method
GET

### Endpoint
/api/og/proxy

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the external image to proxy.

#### Request Body
- **options** (OGProxyOptions) - Optional - Configuration options for the proxy.
  - **userAgent** (string) - Optional - Custom user agent string to use for the request. Defaults to 'Mozilla/5.0 (compatible; OG-Proxy/1.0)'.
  - **cacheMaxAge** (number) - Optional - Cache duration in seconds. Defaults to 3600 (1 hour).

### Request Example
```typescript
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  // Cache for 24 hours
  });
}
```

### Response
#### Success Response (200)
Returns the binary data of the image with appropriate headers, respecting the provided options.
- **Content-Type** (string) - The content type of the original image.
- **Cache-Control** (string) - Cache control headers reflecting the `cacheMaxAge` setting.

#### Response Example
```json
{
  "image": "binary data"
}
```

### Error Handling
- **400** : Missing URL parameter.
- **500** : Failed to fetch the image.
- **Original status** : If the external server returns an error, that status is forwarded.
```

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

### BlockQuote Component Usage

Source: https://docs.once-ui.com/once-ui/components/blockquote

Example of how to use the BlockQuote component with various props for customization.

```APIDOC
## BlockQuote Component

### Description
Displays quoted text with options for styling, author, and source link.

### Props
#### children
- **Type**: `React.ReactNode`
- **Description**: The content of the quote.

#### subline
- **Type**: `ReactNode.ReactNode`
- **Description**: Additional subline content for the quote.

#### author
- **Type**: `{ name?: string; avatar?: string }`
- **Description**: Information about the author of the quote.

#### link
- **Type**: `{ href?: string; label?: string }`
- **Description**: A link to the source of the quote.

#### separator
- **Type**: `top | bottom | both | none`
- **Default**: `both`
- **Description**: Specifies the separator style for the quote.

#### align
- **Type**: `left | center | right`
- **Default**: `center`
- **Description**: Aligns the quote content.

#### className
- **Type**: `string`
- **Description**: Custom CSS class name for the component.

#### style
- **Type**: `React.CSSProperties`
- **Description**: Custom inline styles for the component.

#### ...flex
- **Type**: `FlexProps`
- **Description**: Flex styling props for layout customization.

### Example Usage
```jsx
<BlockQuote 
  border="neutral-alpha-medium"
  background="surface"
  radius="xl"
  padding="l"
  align="left"
  separator="none"
  author={{
    name: "Lorant",
  }}
  link={{
    href: "once-ui.com/truth",
    label: "once-ui.com"
  }}>
  <Text variant="heading-default-l">“The first time a stranger pays for something you’ve built — something that came entirely from your mind — your worldview changes forever.”</Text>
</BlockQuote>
```

### Accessibility Considerations
BlockQuote renders a semantic `<blockquote>` element. Provide a link URL when available to reference the source. Ensure sufficient color contrast if you override the default background or onBackground props.
```

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

### Displaying Keyboard Shortcuts

Source: https://docs.once-ui.com/once-ui/components/kbd

Shows how to combine multiple Kbd components to represent keyboard shortcuts.

```html
<Flex gap="8" vertical="center">
  <Kbd>Ctrl</Kbd>
  <Text>+</Text>
  <Kbd>C</Kbd>
  <Text>to copy</Text>
</Flex>
```

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

### Mask Effect

Source: https://docs.once-ui.com/once-ui/components/background

Example of using the mask property to create a spotlight or reveal effect.

```APIDOC
## Mask Effect

### Description
Create a spotlight or reveal effect with the mask property.

### Props
- **fill** (boolean) - Optional - Whether the background should fill its container.
- **height** (number) - Optional - Specifies the height of the background element.
- **gradient** (GradientProps) - Optional - Configuration for the gradient effect.
- **lines** (LinesProps) - Optional - Configuration for the lines effect.
- **mask** (MaskProps) - Required - Configuration for the mask effect.
  - **x** (number) - Optional - Horizontal position of the mask center. Defaults to `unset`.
  - **y** (number) - Optional - Vertical position of the mask center. Defaults to `unset`.
  - **radius** (number) - Optional - Radius of the mask. Defaults to `50`.
  - **cursor** (boolean) - Optional - Whether the mask follows the cursor. Defaults to `false`.

### Example Usage
```jsx
<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
  }}
/>
```
```

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

### Grid Background

Source: https://docs.once-ui.com/once-ui/components/background

Example of creating grid backgrounds with customizable color, opacity, and dimensions.

```APIDOC
## Grid Background

### Description
Create grid backgrounds with customizable color, opacity, and dimensions.

### Props
- **fill** (boolean) - Optional - Whether the background should fill its container.
- **height** (number) - Optional - Specifies the height of the background element.
- **grid** (GridProps) - Required - Configuration for the grid effect.
  - **display** (boolean) - Optional - Whether to display the grid. Defaults to `false`.
  - **opacity** (number) - Optional - Opacity of the grid. Defaults to `1`.
  - **color** (string) - Optional - Color of the grid. Defaults to `neutral-medium`.
  - **width** (string) - Optional - Width of the grid cells. Defaults to `32px`.
  - **height** (string) - Optional - Height of the grid cells. Defaults to `32px`.

### Example Usage
```jsx
<Background
  fill
  height={16}
  grid={{
    display: true,
    opacity: 1,
    color: "neutral-alpha-medium",
    width: "1rem",
    height: "1rem"
  }}
/>
```
```
Tokens:
Raw