`.
---
## Variants
MegaMenu supports interaction-based variants.
```tsx
```
**Available variants:**
- closed
- open
- trigger-active
- content-visible
**Guidelines:**
- Use MegaMenu for high-density navigation only
- Avoid using for simple dropdown patterns
---
## Sizes
No intrinsic size variants.
Sizing is consumer-driven via custom class overrides.
Default behavior:
- Trigger: intrinsic content width
- Content: `min-width: 480px`
- Panel supports responsive overrides
---
## Shapes / Modes
**Behavioral modes**
- Closed (default)
- Open (context-driven)
**Interaction modes**
- Toggle click
- Outside click dismissal
- Escape key dismissal
- Trigger focus restoration
**Layout modes**
- Single column
- Multi-column grid
- Marketing hero panel
- Mixed content navigation
---
z-dropdown`
- `--color-primary`
- `--fg-default`
Shadow and spacing tokens define panel elevation and density.
---
## Accessibility
Implemented:
- `aria-expanded` on trigger
- `aria-controls` linkage
- Unique ID generation
- Escape key close + focus restore
- Focus-visible outline
- Outside click dismissal
Limitations:
- No roving tabindex menu navigation
- No arrow-key navigation
- No typeahead navigation
- Role `menu` without menuitem semantics
- No focus trap
---
## Animation
Entrance animation:
- Scale + translate + fade
- Transform origin anchored to trigger
- Motion respects `prefers-reduced-motion`
Chevron rotation indicates state transition.
---
## Architectural notes
Key behaviors:
- Context-driven open state
- Compound component pattern
- Ref synchronization between root and trigger
- Document-level listeners for dismissal
- Lazy mount of content (performance)
- ID-based accessibility linkage
- CSS animation entrance for GPU-accelerated motion
Tradeoffs:
- No portal rendering → constrained by stacking context
- Menu positioning not collision-aware
- Outside click detection relies on DOM containment
---
## Best practices
### Do
- Use for complex product navigation
- Compose with Grid/Flex for panel structure
- Provide large touch targets inside panel
- Keep trigger labels concise
- Implement responsive content layout
### Don’t
- Use as replacement for simple dropdown
- Overload with excessive nested menus
- Place inside overflow-hidden containers
- Depend on default width for mobile layouts
- Mix unrelated navigation categories
---
## API Reference
---
### Document: nui/components/modal/page.mdx
# Modal
A portal-based, fully accessible dialog primitive engineered for interruptive workflows, confirmations, and multi-step forms. Implements WAI-ARIA 1.2 modal dialog standards, focus trapping, background inerting, body scroll locking, and physics-based entrance/exit transitions.
```tsx
import { Modal } from '@nofinite/nui';
```
---
## Interactive Preview
---
## Anatomy & Modes
NUI Modal can be used as a self-contained single element via declarative props (matching Storybook's default pattern) or composed via structured compound components for custom layout arrangements:
### Declarative Props Mode (Recommended)
```tsx
}
>
Modal body content goes here.
```
### Compound Components Mode
```tsx
Modal Title
Descriptive helper subtitle.
{/* Scrollable content area */}
{/* Action buttons */}
```
| Component / Prop | Description |
| :--- | :--- |
| `Modal` | The root portal controller and backdrop overlay container. |
| `title` | Accessible title prop rendered into `h2.modal-title`. |
| `description` | Accessible description subtitle rendered into `p.modal-description`. |
| `footer` | Custom footer actions container rendered with border separation and flex-end alignment. |
| `Modal.Header` | Container for the dialog title and descriptive subtitle. |
| `Modal.Title` | Accessible heading (``) linked via `aria-labelledby`. |
| `Modal.Description` | Accessible subtitle (`
`) linked via `aria-describedby`. |
| `Modal.Body` | Main scrollable content region with responsive padding. |
| `Modal.Footer` | Bottom action bar with border separation and flex-end alignment. |
---
## Usage Examples
### 1. Standard Declarative Modal
Self-contained modal using `title`, `description`, and `footer` props:
```tsx
import React, { useState } from 'react';
import { Button, Modal } from '@nofinite/nui';
export default function DeploymentSettings() {
const [open, setOpen] = useState(false);
return (
<>
setOpen(false)}
title="Production Deployment"
description="Configure edge nodes and SSL certificate options."
footer={
<>
}
>
Your application will be distributed across 35 edge regions with automated fallback routing and instant cache invalidation.
);
}
```
---
### 2. Form Dialog with Initial Focus
Automatically focus an input field when the dialog opens using `initialFocusRef`:
```tsx
import React, { useState, useRef } from 'react';
import { Button, Modal, Input } from '@nofinite/nui';
export default function RenameProjectModal() {
const [open, setOpen] = useState(false);
const inputRef = useRef(null);
return (
<>
setOpen(false)}
initialFocusRef={inputRef}
>
Rename Project
Choose a unique identifier for your workspace.
);
}
```
---
### 3. Non-Dismissible Transactional Modal
Prevent accidental dismissal during critical or destructive workflows:
```tsx
{}}
disableClickOutside
disableEsc
hideCloseButton
>
Migrating Database
Please do not close this window while the migration executes.
```
---
## Keyboard Interaction
| Key | Behavior |
| :--- | :--- |
| Escape | Closes the modal and restores focus to the previously focused trigger element (unless `disableEsc` is active). |
| Tab | Traps and cycles focus forward through all interactive elements within the modal dialog. |
| Shift + Tab | Cycles focus backwards within the modal focus trap. |
---
## Accessibility (WAI-ARIA)
- **Role & Semantics:** Root dialog renders `role="dialog"` and `aria-modal="true"`.
- **Labeling:** Automatically links `aria-labelledby` to `Modal.Title` and `aria-describedby` to `Modal.Description`.
- **Focus Management:** Focus is automatically trapped inside the dialog upon mounting and returned to the trigger element on close.
- **Background Inerting:** All sibling nodes outside the portal are marked `inert` to prevent screen reader bleed.
- **Scroll Locking:** Automatically locks body scroll with padding compensation to avoid layout shift.
---
## Design Tokens & NUICSS Superclasses
NUI Modal strictly adheres to semantic NUICSS tokens and superclasses:
| Superclass / Token | Type | Usage |
| :--- | :--- | :--- |
| `modal-box` | Superclass | Dialog container surface with elevation, radius, and max-width. |
| `modal-header` | Superclass | Top header area with title spacing. |
| `modal-title` | Superclass | Semantically styled dialog title. |
| `modal-description`| Superclass | Muted subtitle text. |
| `modal-body` | Superclass | Scrollable body area with responsive gutters. |
| `modal-footer` | Superclass | Bottom border-separated action bar. |
| `modal-close` | Superclass | Absolute close button in the upper-right corner. |
| `bg-overlay` | Token | Semi-transparent dimmed backdrop (`--bg-overlay`). |
| `bg-surface` | Token | Dialog panel background surface (`--bg-surface`). |
| `border-default` | Token | Container border token (`--border-default`). |
---
## Best Practices
### Do
- Always provide clear `Modal.Title` and `Modal.Description` for screen reader context.
- Use `initialFocusRef` for form dialogs to guide keyboard users directly to the first input.
- Provide explicit action buttons in `Modal.Footer` to clearly communicate outcomes.
### Don't
- Do not nest modals inside other modals; use sequential drawers or full-page workflows instead.
- Avoid using modals for non-interruptive information that could live directly on the page canvas.
- Do not disable outside click or Escape dismissal without an explicit functional reason (such as unsaved changes).
---
## API Reference
---
### Document: nui/components/multiselect/page.mdx
# Multi Select
A fully accessible, token-driven MultiSelect component built with strict WAI-ARIA compliance.
```tsx
import { MultiSelect } from '@nofinite/nui';
```
---
## Interactive Preview
---
## Usage
### Basic Example
```tsx
import { MultiSelect } from '@nofinite/nui';
```
---
## API Reference
---
## Accessibility & Guidelines
- **Semantic Tokens:** Built strictly using Nuicss semantic tokens (`bg-surface`, `text-default`, `border-subtle`, `bg-primary`).
- **Keyboard Navigation:** Adheres to strict WAI-ARIA standards.
- **Screen Reader Support:** Includes semantic roles and live regions where appropriate.
---
### Document: nui/components/nuiprovider/page.mdx
# NUI Provider
The `NUIProvider` is the root context wrapper for all NUI applications. It manages global theme state (`light`, `dark`, or `system`), synchronizes preferences with `localStorage`, listens for operating system theme changes, and exposes the `useTheme` hook.
```tsx
import { NUIProvider, useTheme } from '@nofinite/nui';
```
---
## Overview
Unlike standard interactive UI widgets, `NUIProvider` is an application-level wrapper component. It injects and manages the `.dark` theme class on your root `` or `` element, ensuring that all NUI component styles automatically adapt between light and dark modes across your application.
All NUI components rely on `NUIProvider` being present at the root of your component tree.
---
## Interactive Demo
---
## Setup & Integration
### Next.js App Router Setup
Place `NUIProvider` in your root layout (`src/app/layout.tsx`). We recommend adding `suppressHydrationWarning` to `` to avoid React hydration mismatches when reading theme preference from `localStorage`:
```tsx
import { NUIProvider } from '@nofinite/nui';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{children}
);
}
```
---
### Vite / React SPA Setup
In single-page React applications, wrap your root application tree in `main.tsx` or `App.tsx`:
```tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { NUIProvider } from '@nofinite/nui';
import App from './App';
ReactDOM.createRoot(document.getElementById('root')!).render(
);
```
---
## Switching Themes with `useTheme`
Use the `useTheme()` hook inside any child component to read the current theme, inspect the resolved DOM theme, or trigger theme changes:
```tsx
import { useTheme, Button, Flex } from '@nofinite/nui';
export function ThemeSwitcher() {
const { theme, resolvedTheme, setTheme } = useTheme();
return (
Current theme: {resolvedTheme}
);
}
```
---
## API Reference
### `NUIProvider` Props
### `useTheme` Hook Return Values
| Property | Type | Description |
| :--- | :--- | :--- |
| `theme` | `'light' \| 'dark' \| 'system'` | The user's active theme setting (including `'system'`). |
| `resolvedTheme` | `'light' \| 'dark'` | The actual computed theme active on the page (`'light'` or `'dark'`). |
| `setTheme` | `(theme: ThemeMode) => void` | Updates the active theme and persists the preference to `localStorage`. |
---
## Best Practices
- **Place at Root:** Always mount `` as close to the root of your application tree as possible.
- **Hydration Safety:** When using Next.js or SSR frameworks, add `suppressHydrationWarning` to the `` tag to prevent client-server theme mismatch warnings.
- **Persistent Key:** The `storageKey` prop defaults to `'nui-theme'`. If you run multiple apps on the same domain, configure unique storage keys to prevent theme conflicts.
---
### Document: nui/components/numberinput/page.mdx
# Number Input
A fully accessible, token-driven NumberInput component built with strict WAI-ARIA compliance.
```tsx
import { NumberInput } from '@nofinite/nui';
```
---
## Interactive Preview
---
## Usage
### Basic Example
```tsx
import { NumberInput } from '@nofinite/nui';
```
---
## API Reference
---
## Accessibility & Guidelines
- **Semantic Tokens:** Built strictly using Nuicss semantic tokens (`bg-surface`, `text-default`, `border-subtle`, `bg-primary`).
- **Keyboard Navigation:** Adheres to strict WAI-ARIA standards.
- **Screen Reader Support:** Includes semantic roles and live regions where appropriate.
---
### Document: nui/components/pagination/page.mdx
# Pagination
A fully accessible, WAI-ARIA compliant pagination component for navigating through pages. Supports first/prev/next/last controls, arrow key navigation, and gap indicators similar to GitHub-style pagination.
```tsx
import { Pagination } from '@nofinite/nui';
```
---
## Interactive Preview
---
## Usage
### Basic Pagination
```tsx
import { Pagination } from '@nofinite/nui';
;
```
---
### Sibling Page Control
```tsx
```
---
### Disabled Pagination
```tsx
```
---
## Page Generation Logic
The component implements **adaptive pagination math**:
- Displays all pages when total is small
- Shows ellipsis only when more than 2 pages are hidden
- Maintains first + last page visibility
- Uses sibling window around current page
Generated item types:
| Type | Description |
| ---------------- | -------------------------- |
| `number` | Page index |
| `left-ellipsis` | Hidden pages before window |
| `right-ellipsis` | Hidden pages after window |
---
## Variants
```tsx
// Default
// Extended window
// Disabled
// Styled
```
**Available variants**
- `default` — Standard pagination
- `extended` — Larger sibling window
- `disabled` — Interaction blocked
- `styled` — Custom styling override
**Guidelines**
- Increase `siblings` for data-heavy navigation
- Keep default sibling size for compact UI
- Disable pagination during async loading states
- Avoid large sibling counts on small screens
---
## States
| State | Description |
| ---------- | ------------------------ |
| `idle` | Default rendering |
| `active` | Current page highlighted |
| `disabled` | Navigation locked |
| `ellipsis` | Hidden page ranges |
| `focused` | Keyboard focus visible |
---
## Keyboard Interaction
| Key | Behavior |
| ------- | ------------------------- |
| `Enter` | Navigate to page |
| `Space` | Trigger page button |
| `Tab` | Move focus across buttons |
---
## Accessibility
- Semantic `