Node.js API Server

https://docs.once-ui.com/once-ui/
Admin
This project appears to be a Node.js application serving an API, possibly including a server...
Tokens:102,630
Snippets:1,276
Trust Score:9.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Basic IconProvider Setup

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

Wrap your application with IconProvider and pass an object of icons as props. This example shows how to import and provide a single icon.

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

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

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

### Simple ToastProvider Setup

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

Wrap your application with ToastProvider to enable toast functionality. This is the most basic setup.

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

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

### Pulse Component Examples

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

Basic examples demonstrating the Pulse component with different sizes and variants.

```html
<Pulse size="s"/>
<Pulse size="m" variant="danger"/>
<Pulse size="l" variant="success"/>
```

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

### Dropdown Placement Example

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

Shows how to control the dropdown's position relative to the trigger element using the 'placement' prop. This example positions the dropdown above the trigger.

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

return (
<Row horizontal="center">
  <DropdownWrapper
    isOpen={isOpen}
    onOpenChange={setIsOpen}
    placement="top"
    trigger={
      <Button onClick={() => setIsOpen(!isOpen)}>
        Open Upward
      </Button>
    }
    dropdown={
      <Column fillWidth padding="4" gap="2">
        <Option
          label="Top option"
          value="top"
          onClick={() => setIsOpen(false)}
        />
        <Option
          label="Middle option"
          value="middle"
          onClick={() => setIsOpen(false)}
        />
        <Option
          label="Bottom option"
          value="bottom"
          onClick={() => setIsOpen(false)}
        />
      </Column>
    }
  />
</Row>
);
```

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

### Removable Chip Example

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

Provides a dynamic example of removable chips, demonstrating how to manage a list of chips and display toast notifications upon removal. This snippet requires the use of `useToast` and `useState` hooks.

```javascript
const { useState } = require('react');
const { useToast } = require('@/hooks/useToast'); // Assuming useToast is imported from a local hook
const { Row } = require('@/components/Row'); // Assuming Row component is imported
const { Chip } = require('@/components/Chip'); // Assuming Chip component is imported

const { addToast } = useToast();
const [chips, setChips] = useState([
  { id: "1", label: "React", icon: "code" },
  { id: "2", label: "TypeScript", icon: "code" },
  { id: "3", label: "Next.js" }
]);

const handleRemove = (id) => {
  const chipToRemove = chips.find(chip => chip.id === id);
  setChips(chips.filter(chip => chip.id !== id));
  
  addToast({
    variant: "danger",
    message: "Removed " + chipToRemove.label + " chip"
  });
};

<Row gap="8" wrap>
  {chips.map(chip => (
    <Chip
      key={chip.id}
      label={chip.label}
      prefixIcon={chip.icon}
      onRemove={() => handleRemove(chip.id)}
    />
  ))}
</Row>
```

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

### CursorCard Placement Options

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

Examples showcasing different placement configurations for the CursorCard overlay content.

```jsx
<CursorCard
  placement="top-left"
  trigger={
    <Button variant="secondary">
      Top left
    </Button>
  }
  overlay={
    <Row>
      Top left
    </Row>
  }
/>

<CursorCard
  placement="top"
  trigger={
    <Button variant="secondary">
      Top
    </Button>
  }
  overlay={
    <Row>
      Top
    </Row>
  }
/>

<CursorCard
  placement="bottom-right"
  trigger={
    <Button variant="secondary">
      Bottom right
    </Button>
  }
  overlay={
    <Row>
      Bottom right
    </Row>
  }
/>
```

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

### Basic LayoutProvider Setup

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

Wrap your application's root component with LayoutProvider to enable window size tracking for responsive components.

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

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

### 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 resizable panels.

```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>
  }
/>
```

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

### 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
```

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

### InteractiveDetails Basic Examples

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

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

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

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

### Compact CodeBlock Example

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

This example shows the CodeBlock in compact mode, which reduces vertical spacing for a more condensed display. Use this when screen real estate is limited.

```javascript
console.log('Compact mode example');
```

```javascript
<CodeBlock
	compact
	copyButton={false}

codes={[ 
		{
			code: "console.log('Compact mode example');",
			language: "javascript",
			label: "Compact"
		}
	]}
/>
```

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

### Basic Textarea Example

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

A simple Textarea component with a label, placeholder, and a fixed number of lines.

```jsx
<Textarea
  id="basic-textarea"
  label="Comments"
  placeholder="Enter your comments here"
  lines={3}
/>
```

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

### 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. This is suitable for basic 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 basic 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>
```

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

### Basic Masonry Grid Example

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

Demonstrates a basic MasonryGrid with default padding, radius, and background. It sets a specific number of columns 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>
```

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

### Configuring Grid Columns

Source: https://docs.once-ui.com/once-ui/basics/structure

Example of setting the number of columns for a Grid component using the 'columns' prop and responsive overrides.

```html
<Grid fillWidth columns="4"/>
  <Row fillWidth/>
  <Row fillWidth/>
  <Row fillWidth/>
  <Row fillWidth/>
  <Row fillWidth/>
  <Row fillWidth/>
</Grid>
```

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

### Advanced ToastProvider Setup with Providers

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

Integrate ToastProvider within a Providers component for advanced setup, allowing breakpoint-based toast positioning. Ensure necessary theme and data providers 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 Modal Example

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

Demonstrates how to open and close a basic modal with content. Requires `useState` for managing visibility and includes a button to trigger the modal.

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

return (
<>
  <Button onClick={() => setIsOpen(true)}>
    Open Modal
  </Button>
  <Modal
    isOpen={isOpen}
    onClose={() => setIsOpen(false)}
    title="Modal Title"
  >
    <Column fillWidth gap="16" marginTop="12">
      <Text>
        Modal content goes here. This area can contain any React components.
      </Text>
      <Input id="example" label="Example input" />
    </Column>
  </Modal>
</>
);
```

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

### Basic Particle Component Usage

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

This is a basic example of how to use the Particle component with common props.

```javascript
<Particle
  fill
  interactive
  speed={3}
  intensity={100}
  height={24}
/>
```

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

### Simple ThemeProvider Setup

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

Wrap your application with ThemeProvider and configure basic style options like theme, brand, accent, and more. This is the most straightforward way to integrate theme management.

```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>
```

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

### Basic Timeline Usage

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

Configure timeline items with label, description, and state 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"
    }
  ]} 
/>
```

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

### Accessible List Example

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

This example demonstrates how to add appropriate ARIA attributes to a list for best accessibility when using the useArrowNavigation hook. Ensure the container has a ref and the onKeyDown handler is attached.

```html
<div
ref={containerRef}
onKeyDown={handleKeyDown}
role="listbox"
aria-label="Options"
>
{items.map((item, index) => (
  <div
    key={index}
    role="option"
    aria-selected={focusedIndex === index}
    tabIndex={focusedIndex === index ? 0 : -1}
  >
    {item}
  </div>
))}
</div>
```

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

### Basic MatrixFx Component

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

A basic example of the MatrixFx component with specified height and colors, triggering the animation on mount.

```jsx
<MatrixFx
  height={24}
  colors={["brand-solid-strong", "accent-solid-strong"]}
  trigger="mount"
  flicker
/>
```

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

### DatePicker Basic Usage

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

A basic example of how to use the DatePicker component to select a date.

```APIDOC
## DatePicker

### Description

Provides an interactive calendar interface for selecting dates.

### Props

- **value** (Date) - The currently selected date.
- **onChange** ((date: Date) => void) - Callback function when the date changes.
- **minDate** (Date) - The minimum selectable date.
- **maxDate** (Date) - The maximum selectable date.
- **previousMonth** (boolean) - Whether to show the previous month navigation button. Defaults to true.
- **nextMonth** (boolean) - Whether to show the next month navigation button. Defaults to true.
- **defaultDate** (Date) - The initial date to display.
- **size** (s | m | l) - The size of the DatePicker. Defaults to 'm'.
- **currentMonth** (number) - The current month to display (0-indexed).
- **currentYear** (number) - The current year to display.
- **onMonthChange** ((increment: number) => void) - Callback function when the month changes.
- **className** (string) - Custom CSS class for the component.
- **style** (React.CSSProperties) - Custom inline styles for the component.
```

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

### InteractiveDetails Tooltip Examples

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

Illustrates how to add tooltips to InteractiveDetails, specifying positions for top and right.

```jsx
<InteractiveDetails 
  label="With tooltip on top"
  iconButtonProps={{ 
    tooltip: "This tooltip appears on top", 
    tooltipPosition: "top" 
  }}
/>

<InteractiveDetails 
  label="With tooltip on right"
  iconButtonProps={{ 
    tooltip: "This tooltip appears on the right", 
    tooltipPosition: "right" 
  }}
/>
```

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

### Basic SegmentedControl Usage

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

Demonstrates the fundamental setup of the SegmentedControl with a list of buttons and an onToggle handler.

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

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

### 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
// Response headers
{
'Content-Type': 'image/jpeg',  // Original content type
'Cache-Control': 'public, max-age=3600'
}
```

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

### Basic CursorCard Usage

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

A basic example demonstrating the CursorCard component with a trigger button and overlay content.

```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>
  }
/>
```

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

### Basic Card Example

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

Demonstrates the basic structure and usage of the Card component with nested content including avatar, text, media, and interaction icons.

```jsx
<Row maxWidth={24}>
  <Card radius="l-4" direction="column" border="neutral-alpha-medium">
    <Row fillWidth paddingX="20" paddingY="12" gap="8" vertical="center">
      <Avatar size="xs" src="/images/avatar.jpg"/>
      <Text variant="label-default-s">Lorant One</Text>
    </Row>
    <Media
      border="neutral-alpha-weak"
      sizes="400px"
      fillWidth
      aspectRatio="4 / 3"
      radius="l"
      alt="Proxima b"
      src="/images/card.jpg"
    />
    <Column fillWidth paddingX="20" paddingY="24" gap="8">
      <Text variant="body-default-xl">Proxima b</Text>
      <Text onBackground="neutral-weak" variant="body-default-s">
        A planet so cruel on the surface, but once you explore what's underneath, you'll question
        everything you know. Yet, you vibe with it.
      </Text>
    </Column>
    <Line background="neutral-alpha-medium" />
    <Row
      paddingX="20" paddingY="12" gap="8" vertical="center"
      textVariant="label-default-s" onBackground="neutral-medium"
    >
      <Icon name="like" size="s" onBackground="neutral-strong" />
      34
      <Icon name="chat" size="s" onBackground="neutral-strong" marginLeft="24" />
      5
    </Row>
  </Card>
</Row>
```

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

### Basic StyleOverlay Usage

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

Renders a StyleOverlay with an IconButton inside. This is a basic example of how to integrate the component.

```jsx
<StyleOverlay>
  <Row paddingTop="8" paddingRight="12">
    <IconButton icon="sparkle" />
  </Row>
</StyleOverlay>
```

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

### Basic CelebrationFx Usage

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

Demonstrates the basic setup for the CelebrationFx component with height, type, and duration.

```jsx
<CelebrationFx
height={20}
type="confetti"
duration={4}
/>
```

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

### DatePicker with Time Selection

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

An example demonstrating how to enable time selection within the DatePicker component.

```APIDOC
## TimePicker Integration

### Description

Enables time selection alongside date selection when the `timePicker` prop is enabled.

### Props

- **value** (Date) - The currently selected date and time.
- **onChange** ((date: Date) => void) - Callback function when the date or time changes.
- **timePicker** (boolean) - Enables the time selection interface. Defaults to false.
- **defaultTime** ({ hours: number; minutes: number }) - The initial time to set when `timePicker` is enabled.
- **minDate** (Date) - The minimum selectable date.
- **maxDate** (Date) - The maximum selectable date.
- **previousMonth** (boolean) - Whether to show the previous month navigation button. Defaults to true.
- **nextMonth** (boolean) - Whether to show the next month navigation button. Defaults to true.
- **defaultDate** (Date) - The initial date to display.
- **size** (s | m | l) - The size of the DatePicker. Defaults to 'm'.
- **currentMonth** (number) - The current month to display (0-indexed).
- **currentYear** (number) - The current year to display.
- **onMonthChange** ((increment: number) => void) - Callback function when the month changes.
- **className** (string) - Custom CSS class for the component.
- **style** (React.CSSProperties) - Custom inline styles for the component.
```

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

### NavIcon Toggle Example

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

Demonstrates how to use the NavIcon component with state management to toggle a navigation menu. Includes basic styling and accessibility attributes.

```javascript
"use client";

import { NavIcon, Flex, Text, Row } 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
      >
        <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"
        >
          <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>
  );
}

```

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

### Set Border Width

Source: https://docs.once-ui.com/once-ui/basics/border

Apply border widths using predefined classes. Example classes include .border-1 and .border-2.

```html
<!-- Example usage for border width -->
<div class="border-1"></div>
<div class="border-2"></div>
```

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

### MobileMegaMenu Usage Example

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

Demonstrates how to hide the MobileMegaMenu component at a large breakpoint or overwrite its visibility at a specific breakpoint.

```tsx
<MobileMegaMenu hide />
<MobileMegaMenu hide={{ l: false }} />
```

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

### Basic Banner Example

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

A simple banner displaying a text announcement. Use this for general notifications.

```html
<Banner>
  Free shipping on orders over $50
</Banner>
```

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

### Basic RadioButton Usage

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

A simple example of a RadioButton with a label and description. Use this for basic selection needs.

```jsx
<RadioButton
  name="subscription"
  value="monthly"
  label="Monthly subscription"
  description="Billed monthly at $9.99"
  onToggle={() => console.log('Selected monthly')}
/>
```

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

### Basic ColorInput Example

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

Demonstrates the basic usage of the ColorInput component to select a brand color. It uses React state to manage the color value and updates it on change.

```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}
/>
```

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

### MatrixFx Click Trigger Example

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

Shows how to use trigger="click" to toggle the effect on click. The animation is controlled by user interaction.

```jsx
<MatrixFx
  height={16}
  trigger="click"
  colors={["brand-solid-medium"]}
/>
```

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

### WeatherFx with Overlay Content

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

Demonstrates how to place content on top of the WeatherFx component, using a rain effect as an example with a heading and text.

```jsx
<WeatherFx
  height={24}
  type="rain"
  colors={["neutral-solid-weak"]}
  intensity={100}
>
  <Column gap="16" fill center>
    <Heading variant="display-strong-xl">
      Rainy Day
    </Heading>
    <Text variant="body-default-l">
      Animated weather effects
    </Text>
  </Column>
</WeatherFx>
```

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

### Error Response Example

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

Shows the JSON structure for an error response when the handleOGProxy function fails to fetch an image.

```json
{
"error": "Failed to fetch image: 404"
}
```

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

### Basic API Route for handleOGFetch

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

This snippet shows the basic setup for an API route in Next.js to use the handleOGFetch utility. It requires importing NextRequest and handleOGFetch.

```typescript
import { NextRequest } from 'next/server';
import { handleOGFetch } from '@once-ui-system/core/server';

export async function GET(request: NextRequest) {
return handleOGFetch(request);
}
```

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

### Basic handleOGProxy API Route

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

This snippet shows the basic setup for an API route using handleOGProxy to proxy external images. It requires NextRequest from 'next/server' and handleOGProxy from '@once-ui-system/core/server'.

```typescript
import { NextRequest } from 'next/server';
import { handleOGProxy } from '@once-ui-system/core/server';

export async function GET(request: NextRequest) {
return handleOGProxy(request);
}
```

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

### Basic FlipFx Example

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

A standard FlipFx component displaying an image on the front and text on the back. Use this for a simple card flip effect.

```jsx
<FlipFx
  minHeight={24}
  aspectRatio={3 / 4}
  front={
    <Media
      fill
      sizes="640px"
      src="/images/docs/once-ui/proxima-b.jpg"
      radius="l"
      border="brand-alpha-weak"
    />
  }
  back={
    <Flex fill background="surface" center
      radius="l"
      border="brand-alpha-weak">
      <Text
        align="center"
        variant="display-default-xs"
      >
        Proxima B
      </Text>
    </Flex>
  }
/>
```

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

### Create New Once UI App

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

Use this command to quickly set up a new Once UI application with the recommended structure and dependencies.

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

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

### Applying Background and Text Colors

Source: https://docs.once-ui.com/once-ui/basics/structure

Use the background prop for element colors and onBackground for text colors. This example shows text on a brand background.

```javascript
<Row background="brand-medium">
  <Text onBackground="brand-medium">
    Text on background
  </Text>
</Row>
```

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

### Highlighting Commands in Text

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

Embed InlineCode components within text to highlight specific commands or package installations. This example shows how to integrate it within a Text component.

```jsx
<Text>
  Install the package using <InlineCode>npm install once-ui</InlineCode> or <InlineCode>yarn add once-ui</InlineCode>.
</Text>
```

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

### Advanced IconProvider Setup with Providers Component

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

Organize your icons in a separate file and use a Providers component to wrap your application with multiple Once UI context providers, including IconProvider.

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

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

### NavIcon Customization Example

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

Illustrates how to customize the appearance of the NavIcon component using props inherited from the Flex component, such as width, height, border, and background.

```html
<NavIcon 
  isActive={isActive} 
  onClick={handleClick}
  width="48"
  height="48"
  border="neutral-alpha-medium"
  background="neutral-strong"
  padding="8"
  radius="full"
/>
```

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

### Advanced ThemeProvider Setup with Configuration File

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

For more complex applications, centralize your style configuration in a `once-ui.config.js` file and use a `Providers` component to wrap your app. This promotes a single source of truth for styling and theme settings.

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

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

### Applying Spacing and Gap

Source: https://docs.once-ui.com/once-ui/basics/structure

Utilize utility props like paddingX, paddingY, and gap for consistent spacing. This example applies horizontal and vertical padding and internal spacing between children.

```javascript
<Column fillWidth>
  <Row fillWidth paddingX="xl" paddingY={2} gap="40" border="neutral-alpha-medium" radius="l">
    <Row fillWidth height="64" />
    <Row fillWidth height="64" />
  </Row>
</Column>
```

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

### CodeBlock with Preview and Styling Options

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

This example shows a CodeBlock configured for a preview with specific padding and styling applied to the preview content. It's useful when the preview area requires custom styling.

```tsx
<CodeBlock
	copyButton
	previewPadding="0"
	preview={
		<Row fillWidth center padding="16">
			<Background
				background="neutral-alpha-weak"
				lines={{display: true, color: "neutral-alpha-weak"}}
				shadow="m"
				fillWidth
			radius="m"
			height={12}
			border="neutral-alpha-medium"
			/>
		</Row>
	}

codes={[ 
		{
			language: "tsx",
			label: "Preview",
			code: "..."
		}
	]} 
/>
```

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

### Return Value Interface and Example

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

Defines the structure of the `Heading` interface returned by the `useHeadingLinks` hook, including `id`, `text`, and `level`. An example output demonstrates the format of the returned array.

```typescript
interface Heading {
  id: string;      // Element ID or generated ID
  text: string;    // Heading text content
  level: number;   // Heading level (2-6)
}

const headings: Heading[] = useHeadingLinks();

// Example output:
// [
//   { id: 'introduction', text: 'Introduction', level: 2 },
//   { id: 'features', text: 'Features', level: 2 },
//   { id: 'api', text: 'API Reference', level: 3 }
// ]
```

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

### TimestampChart Example

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

Demonstrates how to use useStreamingViewport to display real-time temperature and humidity data with timestamped X-axis ticks. The hook manages data updates and viewport.

```typescript
function TimestampChart() {
const { data, xDomain, running, setRunning } = useStreamingViewport({
  initialData: Array.from({ length: 20 }, (_, i) => ({
    timestamp: Date.now() - (20 - i) * 2000,
    temperature: 20 + Math.random() * 5,
    humidity: 60 + Math.random() * 10
  })),
  windowSize: 20,
  intervalMs: 2000,
  xKey: 'timestamp',
  numericKeys: ['temperature', 'humidity'],
  getNextTarget: ({ lastPoint }) => ({
    temperature: lastPoint.temperature + (Math.random() - 0.5) * 2,
    humidity: lastPoint.humidity + (Math.random() - 0.5) * 5
  })
});

return (
  <LineChart width={800} height={400} data={data}>
    <XAxis
      dataKey="timestamp"
      domain={xDomain}
      type="number"
      scale="time"
      tickFormatter={(ts) => new Date(ts).toLocaleTimeString()}
    />
    <Line dataKey="temperature" stroke="#ff4444" />
    <Line dataKey="humidity" stroke="#4444ff" />
  </LineChart>
);
}
```

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

### Launch Countdown Example

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

A complete example of a launch countdown using CountdownFx within a layout structure, featuring a strong display variant and DD:HH:MM:SS format. The countdown is set for 7 days in the future.

```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>
```

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

### MatrixFx Hover Trigger Example

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

Demonstrates using trigger="hover" for native hover support. The dots progressively appear on hover and smoothly reverse when the mouse moves away. This example also includes a bulge animation.

```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>
```

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

### Responsive Flex Component Example

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

This example demonstrates how the useResponsiveClasses hook is utilized indirectly by the Flex component. It shows a Flex component with responsive direction props, where the hook automatically applies 'flex-column' on small screens and 'flex-row' on medium and larger screens.

```jsx
<Flex direction={{ s: 'column', m: 'row' }}>
{
/* Hook applies 'flex-column' on small screens */
}
{
/* Hook applies 'flex-row' on medium+ screens */
}
</Flex>
```

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

### EmojiPickerDropdown Placement Options

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

Demonstrates controlling the dropdown's placement relative to the trigger using the 'placement' prop. Includes examples for 'top', 'bottom', 'left', and 'right'.

```jsx
const [selectedEmoji, setSelectedEmoji] = useState("");

<Row gap="16" wrap vertical="center">
<EmojiPickerDropdown
  trigger={<Button label="Top" />}
  onSelect={(emoji) => setSelectedEmoji(emoji)}
  placement="top"
/>
<EmojiPickerDropdown
  trigger={<Button label="Bottom" />}
  onSelect={(emoji) => setSelectedEmoji(emoji)}
  placement="bottom"
/>
<EmojiPickerDropdown
  trigger={<Button label="Left" />}
  onSelect={(emoji) => setSelectedEmoji(emoji)}
  placement="left"
/>
<EmojiPickerDropdown
  trigger={<Button label="Right" />}
  onSelect={(emoji) => setSelectedEmoji(emoji)}
  placement="right"
/>
{selectedEmoji && (
  <Text variant="heading-default-xl">
    {selectedEmoji}
  </Text>
)}
</Row>
```

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

### Masonry Grid with Responsive Columns

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

Illustrates how to control the number of columns for different screen sizes using responsive props like 'm' and 's'.

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

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

### Basic AvatarGroup Example

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

A standard AvatarGroup displaying a mix of image and text-based avatars.

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

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

### Advanced DataThemeProvider Setup with Configuration File

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

Centralize style configurations in a separate file (e.g., once-ui.config.js) and use a Providers component for a single source of truth. 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>
  );
}
```

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

### Basic ContextMenu Usage

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

Demonstrates how to implement a ContextMenu with a dropdown containing options like Edit, Duplicate, and Delete. The dropdown is structured using Column and includes separators.

```jsx
<ContextMenu
  placement="bottom-start"
  dropdown={
    <Column gap="2" padding="4" minWidth={10}>
      <Option
        hasPrefix={<Icon size="xs" name="edit" onBackground="neutral-weak" />}
        label="Edit"
        value="edit"
      />
      <Option
        hasPrefix={<Icon size="xs" name="copy" onBackground="neutral-weak" />}
        label="Duplicate"
        value="duplicate"
      />
      <Line marginY="2" />
      <Option
        hasPrefix={<Icon size="xs" name="delete" onBackground="danger-medium" />}
        danger
        label="Delete"
        value="delete"
      />
    </Column>
  }
>
  <Row fillWidth align="center" horizontal="center" padding="40" radius="l" background="surface" border="neutral-alpha-medium" textVariant="label-default-m">Right click me</Row>
</ContextMenu>
```

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

### Displaying Keyboard Shortcuts

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

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

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

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

### Hover Trigger Example

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

Configures CelebrationFx to trigger on hover, providing an interactive celebration experience.

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

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

### System Monitoring Dashboard with useStreamingData

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

This example demonstrates a system monitoring dashboard using the useStreamingData hook. It visualizes CPU, memory, and network usage with real-time updates and allows pausing/resuming the data stream.

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

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

### Basic Skeleton Usage

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

Demonstrates the basic usage of the Skeleton component with different shapes and sizes. Use this to quickly add placeholder elements.

```html
<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" />
```

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

### BlockQuote with Top Separator

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

Adjusts the visibility of separator lines. This example shows a top separator.

```jsx
<BlockQuote separator="top">
  “We weren’t interested in selling visions that fall apart the moment someone buys in. We wanted to build products that last.”
</BlockQuote>
```

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

### 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.

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

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

### Basic Dropdown Usage

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

Demonstrates a simple dropdown with three selectable options. Use this for standard selection scenarios.

```javascript
const [selected, setSelected] = useState("");

const handleSelect = (value: string) => {
  setSelected(value);
};

return (
  <Dropdown
    selectedOption={selected}
    onSelect={handleSelect}
    padding="4"
    radius="m-4"
  >
    <Option
      label="Option 1"
      value="option1"
      selected={selected === "option1"}
      onClick={handleSelect}
    />
    <Option
      label="Option 2"
      value="option2"
      selected={selected === "option2"}
      onClick={handleSelect}
    />
    <Option
      label="Option 3"
      value="option3"
      selected={selected === "option3"}
      onClick={handleSelect}
    />
  </Dropdown>
);
```

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

### Button with Icons

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

Examples of adding icons to buttons, either as a prefix or suffix, to enhance visual communication.

```html
<Button prefixIcon="check">
  Confirm
</Button>
<Button suffixIcon="chevronRight">
  Next
</Button>
<Button prefixIcon="info" suffixIcon="chevronRight">
  Learn more
</Button>
```

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

### Basic AccordionGroup Example

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

This snippet demonstrates how to use the AccordionGroup component with a list of items, each having a title and content.

```jsx
<AccordionGroup
  items={[
    {
      title: "First Item",
      content:
        <Text onBackground="neutral-weak">
          Content for the first item
        </Text>
    },
    {
      title: "Second Item",
      content:
        <Text onBackground="neutral-weak">
          Content for the second item
        </Text>
    },
    {
      title: "Third Item",
      content:
        <Text onBackground="neutral-weak">
          Content for the third item
        </Text>
    }
  ]}
/>
```

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

### Basic Heading Usage

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

Demonstrates the basic usage of the Heading component with different variants and semantic HTML elements.

```javascript
<Heading variant="heading-strong-xl">
  Heading 1
</Heading>
<Heading variant="heading-strong-l" as="h2">
  Heading 2
</Heading>
<Heading variant="heading-strong-m" as="h3">
  Heading 3
</Heading>
<Heading variant="heading-strong-s" as="h4">
  Heading 4
</Heading>
```

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

### MatrixFx with Specified Reveal Direction

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

Controls the starting point of the reveal animation using the 'revealFrom' prop.

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