Ninna UI v0.6.0 - Full Component API Source Reference
This document contains the unminified TypeScript Implementation and Styling layer of all Ninna UI components (v0.6.0). It is explicitly designed for LLMs to read and instantly understand the current API boundaries, DOM structures, and prop-types of the design system.
IMPORTANT: Each component is exported from exactly ONE package. Import from the package shown next to each component below.
Use version 0.6.0 or later — install with @latest (e.g. pnpm add @ninna-ui/core@latest). Do NOT use 0.1.0.
## Component API Quick Reference (auto-generated)
Exact import + props for every documented component. Always import from the package shown.
======================================================
@ninna-ui/primitives
======================================================
### Avatar
import { Avatar } from "@ninna-ui/primitives";
Avatar props:
- src: string — Image source URL for the avatar
- alt: string — Alternative text for the image
- name: string — Name used to generate initials fallback (e.g., 'John Doe' → 'JD')
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the avatar
- shape: 'circle' | 'square' [default: 'circle'] — Shape of the avatar
- radius: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full' [default: 'md'] — Border radius when shape is 'square'
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'neutral'] — Color theme for fallback background
- showRing: boolean [default: false] — Show a colored ring around the avatar
- ringColor: Color — Ring color (defaults to color prop)
- fallback: React.ReactNode — Custom fallback content when image fails or no src
- showFallbackIcon: boolean [default: false] — Show fallback icon instead of initials
- loading: 'eager' | 'lazy' [default: 'lazy'] — Image loading attribute
- className: string — Additional CSS classes
Avatar Group props:
- max: number — Maximum number of avatars to show before overflow indicator
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size for all avatars in the group
- spacing: 'tight' | 'normal' | 'loose' [default: 'normal'] — Spacing between avatars (overlap amount)
- children (required): React.ReactNode — Avatar components to display in the group
- className: string — Additional CSS classes
Example:
```tsx
import { Avatar , Code } from "@ninna-ui/primitives";
export default function Example() {
return (
);
}
```
### Badge
import { Badge } from "@ninna-ui/primitives";
Badge props:
- variant: 'solid' | 'soft' | 'outline' [default: 'soft'] — Visual style variant of the badge
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color theme of the badge
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the badge
- radius: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full' [default: 'md'] — Border radius style
- className: string — Additional CSS classes
- children: React.ReactNode — Content to display inside the badge
Example:
```tsx
import { Badge } from "@ninna-ui/primitives";
export default function Example() {
return (
New
);
}
```
### Blockquote
import { Blockquote } from "@ninna-ui/primitives";
Blockquote props:
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color variant of the blockquote
- variant: 'outline' | 'solid' | 'soft' [default: 'outline'] — Visual style variant
- cite: string — URL of the citation source (for the cite attribute)
- citeSource: ReactNode — Citation author/source to display
- showIcon: boolean [default: false] — Whether to show a quote icon
- icon: ReactNode — Custom quote icon
- className: string — Additional CSS classes
Example:
```tsx
import { Blockquote } from "@ninna-ui/primitives";
export default function Example() {
return (
The only way to do great work is to love what you do.
);
}
```
### Button
import { Button } from "@ninna-ui/primitives";
Button props:
- variant: 'solid' | 'soft' | 'outline' | 'ghost' | 'text' [default: 'solid'] — Visual style variant of the button
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color theme of the button
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the button
- radius: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full' [default: 'md'] — Border radius of the button
- loading: boolean [default: false] — Shows loading spinner and disables the button
- disabled: boolean [default: false] — Disables the button
- fullWidth: boolean [default: false] — Makes the button full width
- leftIcon: React.ReactNode — Icon to display on the left side
- rightIcon: React.ReactNode — Icon to display on the right side
- className: string — Additional CSS classes
- children (required): React.ReactNode — Button content
Example:
```tsx
import { Button } from "@ninna-ui/primitives";
export default function Example() {
return (
);
}
```
### Code
import { Code } from "@ninna-ui/primitives";
Code props:
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'neutral'] — Color variant of the code
- size: 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl' [default: 'sm'] — Text size of the code
- className: string — Additional CSS classes
Example:
```tsx
import { Code } from "@ninna-ui/primitives";
export default function Example() {
return (
Run npm install to install dependencies.
);
}
```
### Divider
import { Divider } from "@ninna-ui/primitives";
Example:
```tsx
import { Divider , Code } from "@ninna-ui/primitives";
export default function Example() {
return (
);
}
```
### Heading
import { Heading } from "@ninna-ui/primitives";
Heading props:
- as: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' [default: 'h2'] — The heading level - determines the semantic HTML element
- size: 'xs' | 'sm' | 'md' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl' — Override the default size for the heading level
- weight: 'light' | 'normal' | 'medium' | 'semibold' | 'bold' — Font weight override
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'neutral'] — Text color
- align: 'left' | 'center' | 'right' — Text alignment
- truncate: boolean [default: false] — Whether to truncate text with ellipsis
- lineClamp: 1 | 2 | 3 | 4 | 5 | 6 — Maximum number of lines before truncating
- noWrap: boolean [default: false] — Whether text should not wrap
- className: string — Additional CSS classes
Example:
```tsx
import { Heading } from "@ninna-ui/primitives";
export default function Example() {
return (
Page Title
);
}
```
### IconButton
import { IconButton } from "@ninna-ui/primitives";
Icon Button props:
- icon (required): React.ReactNode — The icon to display in the button
- aria-label (required): string — Accessible label for the button (required for screen readers)
- variant: 'solid' | 'soft' | 'outline' | 'ghost' | 'text' [default: 'solid'] — Visual style variant of the button
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color theme of the button
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the button (square dimensions)
- radius: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full' [default: 'md'] — Border radius of the button
- loading: boolean [default: false] — Shows loading spinner and disables the button
- disabled: boolean [default: false] — Disables the button
- className: string — Additional CSS classes
Example:
```tsx
import { IconButton } from "@ninna-ui/primitives";
import { Heart } from "lucide-react";
export default function Example() {
return (
}
color="primary"
aria-label="Like"
/>
);
}
```
### Kbd
import { Kbd } from "@ninna-ui/primitives";
Kbd props:
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'neutral'] — Color variant
- size: 'xs' | 'sm' | 'md' | 'lg' [default: 'sm'] — Size variant
- className: string — Additional CSS classes
Example:
```tsx
import { Kbd } from "@ninna-ui/primitives";
export default function Example() {
return (
⌘+C
);
}
```
### Link
import { Link } from "@ninna-ui/primitives";
Link props:
- href: string — The URL the link points to
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' — Text size - matches Text component sizes. Inherits from parent when not set.
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'neutral'] — Color variant of the link
- underline: 'always' | 'hover' | 'none' [default: 'hover'] — Underline behavior
- external: boolean [default: false] — Whether the link opens in a new tab (adds target="_blank" and rel="noopener noreferrer")
- showExternalIcon: boolean [default: true] — Whether to show an external link icon for external links
- externalIcon: ReactNode — Custom external icon to display
- className: string — Additional CSS classes
Example:
```tsx
import { Link } from "@ninna-ui/primitives";
export default function Example() {
return (
About Us
);
}
```
### LinkOverlay
import { LinkOverlay } from "@ninna-ui/primitives";
Link Box props:
- as: 'div' | 'article' | 'section' | 'aside' | 'header' | 'footer' | 'main' | 'nav' [default: 'div'] — The HTML element to render as
- className: string — Additional CSS classes
Link Overlay props:
- href: string — The URL the link points to
- external: boolean [default: false] — Whether the link opens in a new tab
- className: string — Additional CSS classes
Example:
```tsx
import { LinkOverlay, LinkBox, Heading, Text } from "@ninna-ui/primitives";
export default function Example() {
return (
Article Title
Article description...
);
}
```
### List
import { List } from "@ninna-ui/primitives";
List props:
- type: 'unordered' | 'ordered' [default: 'unordered'] — List type (ul or ol)
- spacing: 'none' | 'sm' | 'md' | 'lg' [default: 'sm'] — Spacing between list items
- marker: 'disc' | 'circle' | 'square' | 'decimal' | 'alpha' | 'roman' | 'none' | 'check' | 'arrow' [default: 'disc' (unordered) / 'decimal' (ordered)] — Marker style
- markerColor: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'neutral'] — Marker color
- icon: ReactNode — Custom icon for all list items
- className: string — Additional CSS classes
List Item props:
- icon: ReactNode — Custom icon for this item (overrides list icon)
- iconColor: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' — Icon color for this item
- className: string — Additional CSS classes
Example:
```tsx
import { List, ListItem } from "@ninna-ui/primitives";
export default function Example() {
return (
First itemSecond itemThird item
);
}
```
### Mark
import { Mark } from "@ninna-ui/primitives";
Mark props:
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'neutral'] — Color variant for the highlight
- className: string — Additional CSS classes
Example:
```tsx
import { Mark, Text } from "@ninna-ui/primitives";
export default function Example() {
return (
This is some text with highlighted content in the middle.
);
}
```
### Text
import { Text } from "@ninna-ui/primitives";
Text props:
- as: 'p' | 'span' | 'div' | 'label' | 'strong' | 'em' | 'small' | 'mark' | 'del' | 'ins' | 'sub' | 'sup' [default: 'p'] — The HTML element to render
- size: 'xs' | 'sm' | 'md' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl' [default: 'md'] — Text size
- weight: 'light' | 'normal' | 'medium' | 'semibold' | 'bold' — Font weight
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'neutral'] — Text color
- align: 'left' | 'center' | 'right' | 'justify' — Text alignment
- truncate: boolean [default: false] — Whether to truncate text with ellipsis
- lineClamp: 1 | 2 | 3 | 4 | 5 | 6 — Maximum number of lines before truncating
- muted: boolean [default: false] — Whether to use muted/secondary text color
- noWrap: boolean [default: false] — Whether text should not wrap
- uppercase: boolean [default: false] — Transform text to uppercase
- lowercase: boolean [default: false] — Transform text to lowercase
- capitalize: boolean [default: false] — Capitalize text
- italic: boolean [default: false] — Apply italic style
- underline: boolean [default: false] — Apply underline decoration
- strikethrough: boolean [default: false] — Apply line-through decoration
- className: string — Additional CSS classes
Example:
```tsx
import { Text } from "@ninna-ui/primitives";
export default function Example() {
return (
Hello, World!
);
}
```
======================================================
@ninna-ui/feedback
======================================================
### Alert
import { Alert } from "@ninna-ui/feedback";
Alert props:
- variant: 'solid' | 'soft' | 'outline' [default: 'soft'] — Visual style variant of the alert
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'neutral'] — Color theme of the alert
- title: ReactNode — Alert title text
- description: ReactNode — Alert description/message text
- icon: ReactNode — Custom icon to display
- showIcon: boolean [default: true] — Whether to show the default icon based on color
- dismissible: boolean [default: false] — Whether the alert can be dismissed
- onDismiss: () => void — Callback when alert is dismissed
- action: ReactNode — Action element (button, link, etc.)
- size: 'sm' | 'md' | 'lg' [default: 'md'] — Size of the alert
- role: string [default: 'alert'] — ARIA role - use 'status' for non-critical messages
- children: ReactNode — Alert content (alternative to description)
- className: string — Additional CSS classes
Example:
```tsx
import { Alert } from "@ninna-ui/feedback";
export default function Example() {
return (
);
}
```
### Circular Progress
import { CircularProgress } from "@ninna-ui/feedback";
Circular Progress props:
- value: number [default: 0] — Current progress value (0 to max)
- max: number [default: 100] — Maximum value for the progress
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the circular progress
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color theme of the progress indicator
- strokeWidth: number — Custom stroke width (overrides size default)
- showValue: boolean [default: false] — Whether to show the value label
- labelPosition: 'center' | 'bottom' | 'none' [default: 'center'] — Position of the value label
- formatLabel: (value: number, max: number) => ReactNode — Custom format function for the value label
- indeterminate: boolean [default: false] — Whether the progress is indeterminate (loading state)
- label: string — Accessible label for screen readers
- children: ReactNode — Custom content to render inside the circle
- className: string — Additional CSS classes for the container
Example:
```tsx
import { CircularProgress } from "@ninna-ui/feedback";
export default function Example() {
return (
);
}
```
### EmptyState
import { EmptyState } from "@ninna-ui/feedback";
Empty State props:
- title (required): string — Title text to display
- description: string — Description text below the title
- icon: React.ReactNode — Icon to display above the title
- size: 'sm' | 'md' | 'lg' [default: 'md'] — Size of the empty state
- action: React.ReactNode — Action button or content below the description
- children: React.ReactNode — Additional content below the description
- className: string — Additional CSS classes
Example:
```tsx
import { EmptyState } from "@ninna-ui/feedback";
import { Button } from "@ninna-ui/primitives";
function SearchIcon(props) {
return (
);
}
export default function Example() {
return (
}
title="No results found"
description="Try adjusting your search or filters."
action={}
/>
);
}
```
### Loading
import { Loading } from "@ninna-ui/feedback";
Loading props:
- variant: 'spin' | 'ping' | 'pulse' | 'dots' [default: 'spin'] — Animation style of the loading indicator
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color theme of the loading indicator
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' [default: 'md'] — Size of the loading indicator
- className: string — Additional CSS classes
- label: string [default: 'Loading...'] — Accessible label for screen readers
Example:
```tsx
import { Loading } from "@ninna-ui/feedback";
export default function Example() {
return (
);
}
```
### Progress
import { Progress } from "@ninna-ui/feedback";
Progress props:
- value: number [default: 0] — Current progress value (0 to max)
- max: number [default: 100] — Maximum value for the progress
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the progress bar
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color theme of the progress bar
- variant: 'default' | 'striped' | 'animated' [default: 'default'] — Visual style variant
- showValue: boolean [default: false] — Whether to show the value label
- labelPosition: 'left' | 'right' | 'top' | 'inside' | 'none' [default: 'right'] — Position of the value label
- formatLabel: (value: number, max: number) => ReactNode — Custom format function for the value label
- indeterminate: boolean [default: false] — Whether the progress is indeterminate (loading state)
- label: string — Accessible label for screen readers
- className: string — Additional CSS classes for the container
- trackClassName: string — Additional CSS classes for the track (background)
- indicatorClassName: string — Additional CSS classes for the indicator (filled part)
Example:
```tsx
import { Progress } from "@ninna-ui/feedback";
export default function Example() {
return (
);
}
```
### Skeleton
import { Skeleton } from "@ninna-ui/feedback";
Skeleton props:
- variant: 'pulse' | 'shine' | 'none' [default: 'pulse'] — Animation variant for the skeleton
- width: string | number — Width of the skeleton (e.g., '200px', 200, '100%')
- height: string | number — Height of the skeleton (e.g., '20px', 20)
- radius: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full' [default: 'md'] — Border radius of the skeleton
- loading: boolean [default: true] — Whether the skeleton is in loading state
- children: React.ReactNode — Content to show when loading is false
- className: string — Additional CSS classes
Skeleton Circle props:
- size: string | number [default: '40px'] — Size of the circle (width and height)
- variant: 'pulse' | 'shine' | 'none' [default: 'pulse'] — Animation variant
- loading: boolean [default: true] — Whether the skeleton is in loading state
- children: React.ReactNode — Content to show when loading is false
- className: string — Additional CSS classes
Skeleton Text props:
- noOfLines: number [default: 3] — Number of text lines to render
- gap: string | number [default: '8px'] — Gap between lines
- variant: 'pulse' | 'shine' | 'none' [default: 'pulse'] — Animation variant
- loading: boolean [default: true] — Whether the skeleton is in loading state
- children: React.ReactNode — Content to show when loading is false
- className: string — Additional CSS classes
Example:
```tsx
import { Skeleton, SkeletonCircle, SkeletonText } from "@ninna-ui/feedback";
export default function Example() {
return (
);
}
```
### Status
import { Status } from "@ninna-ui/feedback";
Status props:
- value: 'success' | 'danger' | 'warning' | 'info' [default: 'info'] — Status value that determines the indicator color
- size: 'sm' | 'md' | 'lg' [default: 'md'] — Size of the status indicator and label
- children: React.ReactNode — Optional label text to display next to the indicator
- className: string — Additional CSS classes
Example:
```tsx
import { Status } from "@ninna-ui/feedback";
export default function Example() {
return (
Completed
);
}
```
### Toast
import { Toast } from "@ninna-ui/feedback";
Toaster props:
- position: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' [default: 'bottom-right'] — Position of toasts on screen
- id: string — Unique identifier - only toasts created with a matching toasterId will be shown by this Toaster. Omit for the default global Toaster.
- max: number [default: 5] — Maximum number of visible toasts
- gap: number [default: 8] — Gap between toasts in pixels
- offset: string | number [default: '1rem'] — Offset from screen edges
- pauseOnHover: boolean [default: true] — Pause auto-dismiss when hovering over toasts
- className: string — Additional CSS classes for the toast container
Toast Options props:
- title: ReactNode — Toast title
- description: ReactNode — Toast description/message
- color: 'primary' | 'secondary' | 'accent' | 'neutral' | 'success' | 'danger' | 'warning' | 'info' [default: 'primary'] — Color theme of the toast
- isLoading: boolean [default: false] — Show a spinning loader icon. Use with duration: 0 to keep the toast persistent until updated.
- variant: 'solid' | 'soft' | 'outline' [default: 'soft'] — Visual variant
- duration: number [default: 5000] — Duration in milliseconds (0 = persistent)
- closable: boolean [default: true] — Whether the toast can be dismissed
- icon: ReactNode — Custom icon
- action: { label: string; onClick: () => void; altText?: string } — Action button configuration
- toasterId: string — Route this toast to a specific Toaster by its id. Omit to send to the default global Toaster.
Toast Methods props:
- toast.create(options): string — Create a new toast. Pass color to indicate type (e.g. success, danger). Returns the toast ID.
- toast.dismiss(id?): void — Dismiss a specific toast by ID, or dismiss all toasts if no ID is provided
- toast.dismissAll(): void — Dismiss all toasts
- toast.update(id, options): void — Update an existing toast by ID
- toast.promise(promise, options): Promise — Show a loading toast while the promise is pending, then update to success or danger on resolution
Example:
```tsx
import { Toaster, toast } from "@ninna-ui/feedback";
// Add Toaster to your app root
export default function App() {
return (
<>
>
);
}
// Use toast anywhere in your app
function MyComponent() {
return (
);
}
```
======================================================
@ninna-ui/forms
======================================================
### Checkbox
import { Checkbox } from "@ninna-ui/forms";
Checkbox props:
- size: 'sm' | 'md' | 'lg' [default: 'md'] — Size of the checkbox
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color theme of the checkbox
- variant: 'outline' | 'soft' | 'solid' [default: 'outline'] — Visual variant of the checkbox
- checked: boolean — Controlled checked state
- defaultChecked: boolean — Default checked state for uncontrolled usage
- onCheckedChange: (checked: boolean) => void — Callback when checked state changes
- label: ReactNode — Label text for the checkbox
- description: ReactNode — Description text below the label
- labelPosition: 'start' | 'end' [default: 'end'] — Position of the label relative to checkbox
- invalid: boolean [default: false] — Whether the checkbox is in an invalid state
- icon: ReactNode — Custom icon for checked state
- indeterminateIcon: ReactNode — Custom icon for indeterminate state
- disabled: boolean [default: false] — Whether the checkbox is disabled
- required: boolean [default: false] — Whether the checkbox is required
Example:
```tsx
import { Checkbox } from "@ninna-ui/forms";
export default function Example() {
return (
);
}
```
### CheckboxGroup
import { CheckboxGroup } from "@ninna-ui/forms";
Checkbox Group props:
- value: string[] — Controlled selected values
- defaultValue: string[] [default: []] — Default selected values (uncontrolled)
- onValueChange: (value: string[]) => void — Callback when selection changes
- orientation: 'vertical' | 'horizontal' [default: 'vertical'] — Layout orientation
- gap: 'sm' | 'md' | 'lg' [default: 'md'] — Gap between items
- size: 'sm' | 'md' | 'lg' [default: 'md'] — Size of all checkboxes in the group
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color theme for all checkboxes
- variant: 'outline' | 'soft' | 'solid' [default: 'outline'] — Visual variant for all checkboxes
- disabled: boolean [default: false] — Disable all checkboxes in the group
- aria-label: string — Accessible label for the checkbox group
Example:
```tsx
import { CheckboxGroup, CheckboxGroupItem } from "@ninna-ui/forms";
```
### Field
import { Field } from "@ninna-ui/forms";
Field props:
- label: string — Label text
- helperText: string — Helper text displayed below the input
- errorText: string — Error text displayed when invalid
- required: boolean [default: false] — Whether the field is required
- invalid: boolean [default: false] — Whether the field is invalid
- disabled: boolean [default: false] — Whether the field is disabled
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the field elements
- optionalText: string — Text displayed on the right side of the label
- children (required): ReactNode — Input component to wrap
- id: string — ID for the field (used to link label with input)
Example:
```tsx
import { Field, Input } from "@ninna-ui/forms";
export default function Example() {
return (
);
}
```
### FileUpload
import { FileUpload } from "@ninna-ui/forms";
File Upload props:
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the file upload component
- accept: string — Accepted file types (e.g., "image/*", ".pdf")
- multiple: boolean [default: false] — Allow multiple file selection
- maxFileSize: number — Maximum file size in bytes
- maxFiles: number [default: 10] — Maximum number of files
- disabled: boolean [default: false] — Whether the upload is disabled
- required: boolean [default: false] — Whether the field is required
- invalid: boolean [default: false] — Whether the upload is in an invalid state
- onFilesChange: (files: File[]) => void — Callback when files are selected
- label: string — Label for the upload area
- helperText: string — Helper text below the upload area
- showFileList: boolean [default: true] — Show file list after selection
- allowDrag: boolean [default: true] — Allow drag and drop
Example:
```tsx
import { FileUpload } from "@ninna-ui/forms";
export default function Example() {
return (
console.log(files)}
/>
);
}
```
### FormControl
import { FormControl } from "@ninna-ui/forms";
Form Control props:
- id: string — Unique ID for the form field (auto-generated if not provided)
- isRequired: boolean [default: false] — Whether the field is required
- isInvalid: boolean [default: false] — Whether the field is in an invalid state
- isDisabled: boolean [default: false] — Whether the field is disabled
- isReadOnly: boolean [default: false] — Whether the field is read-only
Form Label props:
- children: ReactNode — Label text content
- className: string — Additional CSS classes
Form Message props:
- type: 'error' | 'success' | 'warning' | 'hint' [default: 'error'] — Message type determines styling
- children: ReactNode — Message content
Example:
```tsx
import { FormControl, FormLabel, FormMessage, Input } from "@ninna-ui/forms";
EmailWe'll never share your email.PasswordPassword must be at least 8 characters.
```
### FormGroup
import { FormGroup } from "@ninna-ui/forms";
Form Group props:
- legend: string — Legend/title rendered inside the fieldset legend element
- description: string — Optional description text below the legend; linked via aria-describedby
- disabled: boolean [default: false] — Disables all form controls inside the fieldset
- required: boolean [default: false] — Marks the group as required (shows * indicator in legend)
- spacing: 'sm' | 'md' | 'lg' [default: 'md'] — Gap between child fields
- direction: 'vertical' | 'horizontal' [default: 'vertical'] — Layout direction of child fields
- id: string — ID for the fieldset element (auto-generated if not provided)
- className: string — Additional CSS classes
- children: ReactNode — Form fields to group together
Example:
```tsx
import { FormGroup, Field, Input } from "@ninna-ui/forms";
```
### Input
import { Input } from "@ninna-ui/forms";
Input props:
- variant: 'outline' | 'filled' | 'flushed' | 'unstyled' [default: 'outline'] — Visual style variant of the input
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color theme of the input focus state
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the input
- clearable: boolean [default: false] — Show clear button when input has value
- onClear: () => void — Callback when clear button is clicked
- showCounter: boolean [default: false] — Show character counter (requires maxLength)
- maxLength: number — Maximum character length
- floatingLabel: string — Floating label text
- fullWidth: boolean [default: true] — Whether the input takes full width of its container
- invalid: boolean [default: false] — Whether the input is in an invalid state
- disabled: boolean [default: false] — Whether the input is disabled
- readOnly: boolean [default: false] — Whether the input is read-only
- className: string — Additional CSS classes
Example:
```tsx
import { Input } from "@ninna-ui/forms";
export default function Example() {
return (
);
}
```
### InputGroup
import { InputGroup } from "@ninna-ui/forms";
Input Group props:
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the input group (affects padding for elements)
- startElement: ReactNode — Element to render at the start (inside the input border)
- endElement: ReactNode — Element to render at the end (inside the input border)
- startElementPointerEvents: 'none' | 'auto' [default: smart] — Override pointer-events on the start slot. By default, decorative content is inert but interactive descendants (button, a, input, [role='button']) receive clicks automatically.
- endElementPointerEvents: 'none' | 'auto' [default: smart] — Override pointer-events on the end slot. See startElementPointerEvents.
Input Addon props:
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the addon
- placement: 'start' | 'end' [default: 'start'] — Position of the addon relative to the input
Example:
```tsx
import { Input, InputGroup, InputAddon } from "@ninna-ui/forms";
import { Search } from "lucide-react";
// With icon inside input
}>
// With addon outside input
https://
```
### NumberInput
import { NumberInput } from "@ninna-ui/forms";
Number Input props:
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the input
- value: number — Controlled value
- defaultValue: number — Default value (uncontrolled)
- onChange: (value: number) => void — Callback when value changes
- min: number — Minimum value
- max: number — Maximum value
- step: number [default: 1] — Step increment
- precision: number — Decimal places
- showStepper: boolean [default: true] — Show stepper buttons
- stepperPosition: 'right' | 'sides' [default: 'right'] — Stepper position
- disabled: boolean [default: false] — Disabled state
- invalid: boolean [default: false] — Invalid state
- readOnly: boolean [default: false] — Read-only state
- required: boolean [default: false] — Whether the input is required
- allowKeyboardInput: boolean [default: true] — Allow typing values directly
- format: (value: number) => string — Custom format function for display value
- parse: (value: string) => number — Custom parse function for input value
- name: string — Name for form submission
- id: string — ID for the input element
- incrementLabel: string [default: 'Increase value'] — Accessible label for the increment button
- decrementLabel: string [default: 'Decrease value'] — Accessible label for the decrement button
Example:
```tsx
import { NumberInput } from "@ninna-ui/forms";
export default function Example() {
return (
);
}
```
### PinInput
import { PinInput } from "@ninna-ui/forms";
Pin Input props:
- length: number [default: 4] — Number of input fields
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the inputs
- type: 'text' | 'password' | 'number' [default: 'text'] — Input type
- mask: boolean [default: false] — Mask input value
- otp: boolean [default: false] — One-time password mode (enables autocomplete)
- value: string — Controlled value
- defaultValue: string — Default value (uncontrolled)
- onChange: (value: string) => void — Callback when value changes
- onComplete: (value: string) => void — Callback when all fields are filled
- disabled: boolean [default: false] — Disabled state
- invalid: boolean [default: false] — Invalid state
- placeholder: string [default: '○'] — Placeholder for each field
- autoFocus: boolean [default: false] — Auto focus the first input on mount
- name: string — Name for hidden form submission input
- aria-label: string [default: 'PIN input'] — Accessible label for the input group
Example:
```tsx
import { PinInput } from "@ninna-ui/forms";
export default function Example() {
return (
console.log('PIN:', pin)}
/>
);
}
```
### RadioGroup
import { RadioGroup } from "@ninna-ui/forms";
Radio Group props:
- size: 'sm' | 'md' | 'lg' [default: 'md'] — Size of the radio buttons
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color theme of the radio buttons
- variant: 'outline' | 'soft' | 'solid' [default: 'outline'] — Visual variant of the radio buttons
- value: string — Controlled value
- defaultValue: string — Default value for uncontrolled usage
- onValueChange: (value: string) => void — Callback when value changes
- orientation: 'horizontal' | 'vertical' [default: 'vertical'] — Layout orientation
- gap: 'sm' | 'md' | 'lg' [default: 'md'] — Gap between radio items
- invalid: boolean [default: false] — Whether the radio group is in an invalid state
- disabled: boolean [default: false] — Whether the radio group is disabled
- required: boolean [default: false] — Whether a selection is required
- name: string — Name for form submission
- loop: boolean — Whether to loop keyboard navigation
- aria-label: string — Accessible label for the radio group
- aria-labelledby: string — ID of the element that labels the radio group
Radio Card props:
- value: string — Value of this radio card (required)
- title: ReactNode — Card title
- description: ReactNode — Card description text
- icon: ReactNode — Icon to display in the card
- disabled: boolean [default: false] — Whether this card is disabled
- aria-label: string — Accessible label for the radio card
- aria-describedby: string — ID of element that describes this radio card
Example:
```tsx
import { RadioGroup, RadioGroupItem } from "@ninna-ui/forms";
export default function Example() {
return (
);
}
```
### Select
import { Select } from "@ninna-ui/forms";
Select props:
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the select
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color theme of the select
- variant: 'outline' | 'filled' | 'flushed' [default: 'outline'] — Visual variant of the select
- value: string — Controlled value
- defaultValue: string — Default value for uncontrolled usage
- onValueChange: (value: string) => void — Callback when value changes
- placeholder: string — Placeholder text when no value is selected
- invalid: boolean [default: false] — Whether the select is in an invalid state
- clearable: boolean [default: false] — Whether the select can be cleared
- onClear: () => void — Callback when clear button is clicked
- disabled: boolean [default: false] — Whether the select is disabled
- required: boolean [default: false] — Whether the select is required
- fullWidth: boolean [default: true] — Whether the select takes full width
- name: string — Name for form submission
- open: boolean — Whether the select dropdown is open (controlled)
- defaultOpen: boolean — Default open state (uncontrolled)
- onOpenChange: (open: boolean) => void — Callback when open state changes
- aria-label: string — Accessible label for the select trigger
- aria-labelledby: string — ID of the element that labels the select
Example:
```tsx
import { Select, SelectItem } from "@ninna-ui/forms";
export default function Example() {
return (
);
}
```
### Slider
import { Slider } from "@ninna-ui/forms";
Slider props:
- size: 'sm' | 'md' | 'lg' [default: 'md'] — Size of the slider
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color theme of the slider
- variant: 'solid' | 'soft' [default: 'solid'] — Visual variant of the slider
- value: number[] — Controlled value (array for range sliders)
- defaultValue: number[] [default: [50]] — Default value for uncontrolled usage
- onValueChange: (value: number[]) => void — Callback when value changes
- onValueCommit: (value: number[]) => void — Callback when value is committed (on mouse up)
- min: number [default: 0] — Minimum value
- max: number [default: 100] — Maximum value
- step: number [default: 1] — Step increment
- label: ReactNode — Label for the slider
- helperText: ReactNode — Helper text below slider
- showValue: boolean [default: false] — Show current value
- showTooltip: boolean [default: false] — Show tooltip on hover/drag
- formatValue: (value: number) => string — Format function for value display
- marks: SliderMark[] | boolean — Marks to display on the slider track
- orientation: 'horizontal' | 'vertical' [default: 'horizontal'] — Orientation of the slider
- inverted: boolean [default: false] — Whether the slider is inverted
- minStepsBetweenThumbs: number — Minimum steps between thumbs for range sliders
- invalid: boolean [default: false] — Whether the slider is in an invalid state
- disabled: boolean [default: false] — Whether the slider is disabled
- name: string — Name for form submission
Example:
```tsx
import { Slider } from "@ninna-ui/forms";
export default function Example() {
return (
);
}
```
### Switch
import { Switch } from "@ninna-ui/forms";
Switch props:
- size: 'sm' | 'md' | 'lg' [default: 'md'] — Size of the switch
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color theme of the switch
- variant: 'solid' | 'soft' | 'outline' [default: 'solid'] — Visual variant of the switch
- checked: boolean — Controlled checked state
- defaultChecked: boolean — Default checked state for uncontrolled usage
- onCheckedChange: (checked: boolean) => void — Callback when checked state changes
- label: ReactNode — Label text for the switch
- description: ReactNode — Description text below the label
- labelPosition: 'start' | 'end' [default: 'end'] — Position of the label relative to switch
- invalid: boolean [default: false] — Whether the switch is in an invalid state
- loading: boolean [default: false] — Whether the switch is in a loading state
- trackLabels: { on?: string; off?: string } — Track labels for on/off states
- thumbIcon: ReactNode — Custom icon for the thumb
- disabled: boolean [default: false] — Whether the switch is disabled
Example:
```tsx
import { Switch } from "@ninna-ui/forms";
export default function Example() {
return (
);
}
```
### Textarea
import { Textarea } from "@ninna-ui/forms";
Textarea props:
- variant: 'outline' | 'filled' | 'flushed' | 'unstyled' [default: 'outline'] — Visual style variant of the textarea
- color: 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger' [default: 'primary'] — Color theme of the textarea focus state
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' [default: 'md'] — Size of the textarea
- resize: 'none' | 'vertical' | 'horizontal' | 'both' [default: 'vertical'] — Resize behavior of the textarea
- rows: number [default: 3] — Number of visible text rows
- autoResize: boolean [default: false] — Auto-resize based on content
- minRows: number [default: 3] — Minimum rows when autoResize is enabled
- maxRows: number — Maximum rows when autoResize is enabled
- showCounter: boolean [default: false] — Show character counter (requires maxLength)
- maxLength: number — Maximum character length
- invalid: boolean [default: false] — Whether the textarea is in an invalid state
- disabled: boolean [default: false] — Whether the textarea is disabled
Example:
```tsx
import { Textarea } from "@ninna-ui/forms";
export default function Example() {
return (
);
}
```
======================================================
@ninna-ui/layout
======================================================
### AspectRatio
import { AspectRatio } from "@ninna-ui/layout";
Aspect Ratio props:
- ratio: number | 'square' | 'video' | 'portrait' | 'wide' [default: 1] — Aspect ratio as width/height number or preset name
- className: string — Additional CSS classes to apply
- style: React.CSSProperties — Inline styles to apply
- children: React.ReactNode — Content to render inside the aspect ratio container
Example:
```tsx
import { AspectRatio } from "@ninna-ui/layout";
export default function Example() {
return (
);
}
```
### Box
import { Box } from "@ninna-ui/layout";
Box props:
- as: ElementType — Semantic HTML element to render (e.g., 'main', 'section')
- className: string — CSS classes to apply
- children: React.ReactNode — Content to render
Example:
```tsx
import { Box } from "@ninna-ui/layout";
export default function Example() {
return (
Content
);
}
```
### Center
import { Center } from "@ninna-ui/layout";
Center props:
- as: ElementType — Semantic HTML element to render
- inline: boolean [default: false] — Use inline-flex instead of flex
- className: string — Additional CSS classes
- children: React.ReactNode — Content to center
Example:
```tsx
import { Center } from "@ninna-ui/layout";
export default function Example() {
return (
);
}
```
### Container
import { Container } from "@ninna-ui/layout";
Container props:
- as: ElementType — Semantic HTML element to render
- maxWidth: ContainerMaxWidth [default: 'lg'] — Maximum width of the container
- center: boolean [default: true] — Center the container horizontally
- padding: boolean [default: true] — Add horizontal padding
- className: string — Additional CSS classes
Example:
```tsx
import { Container } from "@ninna-ui/layout";
export default function Example() {
return (
Page Content
Your content here...
);
}
```
### Flex
import { Flex } from "@ninna-ui/layout";
Flex props:
- as: ElementType — Semantic HTML element to render
- direction: 'row' | 'column' | 'row-reverse' | 'column-reverse' [default: 'row'] — Flex direction
- gap: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12' | '16' — Gap between items
- align: 'start' | 'center' | 'end' | 'stretch' | 'baseline' — Align items on cross axis
- justify: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' — Justify items on main axis
- wrap: 'wrap' | 'nowrap' | 'wrap-reverse' — Flex wrap behavior
- inline: boolean [default: false] — Use inline-flex instead of flex
- className: string — Additional CSS classes
Example:
```tsx
import { Flex } from "@ninna-ui/layout";
export default function Example() {
return (
Username
);
}
```
### Grid
import { Grid } from "@ninna-ui/layout";
Grid props:
- as: ElementType — Semantic HTML element to render
- columns: GridColumns | ResponsiveValue [default: 1] — Number of columns or breakpoint map
- rows: 1 | 2 | 3 | 4 | 5 | 6 | 'none' — Number of rows
- gap: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12' | '16' [default: '4'] — Gap between items
- rowGap: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12' | '16' — Row gap (overrides gap)
- columnGap: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12' | '16' — Column gap (overrides gap)
- flow: 'row' | 'column' | 'dense' | 'row-dense' | 'column-dense' — Grid flow direction
- align: 'start' | 'center' | 'end' | 'stretch' | 'baseline' — Align grid items on the cross axis
- className: string — Additional CSS classes
Example:
```tsx
import { Grid } from "@ninna-ui/layout";
export default function Example() {
return (
);
}
```
### Separator
import { Separator } from "@ninna-ui/layout";
Separator props:
- as: ElementType [default: "hr"] — Semantic HTML element to render
- orientation: 'horizontal' | 'vertical' [default: 'horizontal'] — Orientation of the separator
- decorative: boolean [default: true] — If true, separator has no semantic meaning
- className: string — Additional CSS classes
Example:
```tsx
import { Separator } from "@ninna-ui/layout";
export default function Example() {
return (
Content above
Content below
);
}
```
### SimpleGrid
import { SimpleGrid } from "@ninna-ui/layout";
Simple Grid props:
- as: ElementType — Semantic HTML element to render (e.g., 'ul')
- columns: number [default: 1] — Fixed number of columns (uses inline style - mutually exclusive with minChildWidth)
- minChildWidth: string — Minimum child width for auto-fit responsive columns (e.g., '200px'). Uses inline style - dynamic values cannot be statically extracted by Tailwind JIT.
- gap: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12' | '16' [default: '4'] — Gap between items (uses Tailwind gap-* classes)
- className: string — Additional CSS classes
Example:
```tsx
import { SimpleGrid } from "@ninna-ui/layout";
export default function Example() {
return (
);
}
```
### Stack
import { Stack } from "@ninna-ui/layout";
Stack props:
- as: ElementType — Semantic HTML element to render
- direction: 'row' | 'column' | 'row-reverse' | 'column-reverse' [default: 'column'] — Direction of the stack layout
- gap: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12' | '16' [default: '4'] — Gap between items
- align: 'start' | 'center' | 'end' | 'stretch' | 'baseline' — Align items on cross axis
- justify: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' — Justify items on main axis
- wrap: boolean [default: false] — Whether items should wrap
- className: string — Additional CSS classes
- children (required): React.ReactNode — Stack content
Example:
```tsx
import { Stack, HStack, VStack } from "@ninna-ui/layout";
export default function Example() {
return (
Item 1
Item 2
Item 3
);
}
```
### Wrap
import { Wrap } from "@ninna-ui/layout";
Wrap props:
- as: ElementType — Semantic HTML element to render
- gap: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12' | '16' [default: '4'] — Gap between items
- align: 'start' | 'center' | 'end' | 'stretch' | 'baseline' — Align items on cross axis
- justify: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' — Justify items on main axis
- className: string — Additional CSS classes
Example:
```tsx
import { Wrap } from "@ninna-ui/layout";
export default function Example() {
return (
Tag 1Tag 2Tag 3
);
}
```
======================================================
@ninna-ui/overlays
======================================================
### Drawer
import { Drawer } from "@ninna-ui/overlays";
Drawer props:
- children (required): ReactNode — Drawer content (Trigger, Content, etc.)
- open: boolean — Controlled open state
- defaultOpen: boolean [default: false] — Default open state (uncontrolled)
- onOpenChange: (open: boolean) => void — Callback when open state changes
- modal: boolean [default: true] — Whether the drawer blocks interaction with the rest of the page
Content props:
- placement: 'left' | 'right' | 'top' | 'bottom' [default: 'right'] — Which edge the drawer slides from
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full' [default: 'md'] — Size of the drawer panel
- description: string — Accessible description for the drawer. Rendered as sr-only when provided.
- closeOnOverlayClick: boolean [default: true] — Whether clicking the overlay closes the drawer
- closeOnEscape: boolean [default: true] — Whether pressing Escape closes the drawer
- onEscapeKeyDown: (event: KeyboardEvent) => void — Callback when Escape key is pressed
- onPointerDownOutside: (event: Event) => void — Callback when pointer clicks outside content
- className: string — Additional CSS classes
Trigger props:
- asChild: boolean [default: false] — Render as child element instead of wrapping button
Close props:
- asChild: boolean [default: false] — Render as child element instead of default close button
Example:
```tsx
import { Drawer } from "@ninna-ui/overlays";
import { Button , Code } from "@ninna-ui/primitives";
export default function Example() {
return (
TitleContent
);
}
```
### DropdownMenu
import { DropdownMenu } from "@ninna-ui/overlays";
Root props:
- children (required): ReactNode — DropdownMenu content (Trigger, Content, etc.)
- open: boolean — Controlled open state
- defaultOpen: boolean [default: false] — Default open state (uncontrolled)
- onOpenChange: (open: boolean) => void — Callback when open state changes
- modal: boolean [default: true] — Whether the dropdown is modal
- dir: 'ltr' | 'rtl' [default: 'ltr'] — Reading direction
Content props:
- side: 'top' | 'right' | 'bottom' | 'left' [default: 'bottom'] — Which side to place the menu
- sideOffset: number [default: 4] — Distance from trigger in pixels
- align: 'start' | 'center' | 'end' [default: 'start'] — Alignment along the side
- loop: boolean [default: true] — Whether to loop keyboard navigation
- avoidCollisions: boolean [default: true] — Whether to avoid collisions with viewport boundary
- className: string — Additional CSS classes
Item props:
- disabled: boolean [default: false] — Whether the item is disabled
- destructive: boolean [default: false] — Whether the item uses danger styling
- onSelect: (event: Event) => void — Callback when the item is selected
- textValue: string — Text value for typeahead search
Checkbox Item props:
- checked: boolean | 'indeterminate' — Whether the item is checked
- onCheckedChange: (checked: boolean) => void — Callback when checked state changes
- disabled: boolean [default: false] — Whether the item is disabled
- onSelect: (event: Event) => void — Callback when the item is selected
- textValue: string — Text value for typeahead search
Radio Group props:
- value: string — Current selected value
- onValueChange: (value: string) => void — Callback when value changes
Radio Item props:
- value (required): string — Value of the radio item
- disabled: boolean [default: false] — Whether the item is disabled
- onSelect: (event: Event) => void — Callback when the item is selected
- textValue: string — Text value for typeahead search
Trigger props:
- asChild: boolean [default: false] — Render as child element instead of wrapping button
Label props:
- inset: boolean [default: false] — Whether the label is inset (indented to align with items)
Example:
```tsx
import { DropdownMenu } from "@ninna-ui/overlays";
import { Button , Code } from "@ninna-ui/primitives";
export default function Example() {
return (
ProfileSettingsSign out
);
}
```
### Modal
import { Modal } from "@ninna-ui/overlays";
Modal props:
- children (required): ReactNode — Modal content (Trigger, Content, etc.)
- open: boolean — Controlled open state
- defaultOpen: boolean [default: false] — Default open state (uncontrolled)
- onOpenChange: (open: boolean) => void — Callback when open state changes
- modal: boolean [default: true] — Whether the modal blocks interaction with the rest of the page
Content props:
- size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full' [default: 'md'] — Size of the modal content panel
- centered: boolean [default: true] — Whether the modal is vertically centered
- description: string — Accessible description for the modal. Rendered as sr-only when provided.
- closeOnOverlayClick: boolean [default: true] — Whether clicking the overlay closes the modal
- closeOnEscape: boolean [default: true] — Whether pressing Escape closes the modal
- onEscapeKeyDown: (event: KeyboardEvent) => void — Callback when Escape key is pressed
- onPointerDownOutside: (event: Event) => void — Callback when pointer clicks outside content
- onInteractOutside: (event: Event) => void — Callback when focus moves outside content
- className: string — Additional CSS classes
Trigger props:
- asChild: boolean [default: false] — Render as child element instead of wrapping button
Close props:
- asChild: boolean [default: false] — Render as child element instead of default close button
Example:
```tsx
import { Modal } from "@ninna-ui/overlays";
import { Button , Code } from "@ninna-ui/primitives";
export default function Example() {
return (
TitleContent here
);
}
```
### Popover
import { Popover } from "@ninna-ui/overlays";
Popover props:
- children (required): ReactNode — Popover content (Trigger, Content, etc.)
- open: boolean — Controlled open state
- defaultOpen: boolean [default: false] — Default open state (uncontrolled)
- onOpenChange: (open: boolean) => void — Callback when open state changes
- modal: boolean [default: false] — Whether the popover is modal
Content props:
- side: 'top' | 'right' | 'bottom' | 'left' [default: 'bottom'] — Which side to place the popover
- sideOffset: number [default: 4] — Distance from trigger in pixels
- align: 'start' | 'center' | 'end' [default: 'center'] — Alignment along the side
- avoidCollisions: boolean [default: true] — Whether to avoid collisions with viewport boundary
- onEscapeKeyDown: (event: KeyboardEvent) => void — Callback when Escape key is pressed
- onPointerDownOutside: (event: Event) => void — Callback when pointer clicks outside content
- onFocusOutside: (event: Event) => void — Callback when focus moves outside content
- className: string — Additional CSS classes
Trigger props:
- asChild: boolean [default: false] — Render as child element instead of wrapping button
Arrow props:
- width: number [default: 10] — Width of the arrow in pixels
- height: number [default: 5] — Height of the arrow in pixels
Close props:
- asChild: boolean [default: false] — Render as child element instead of default close button
Example:
```tsx
import { Popover } from "@ninna-ui/overlays";
import { Button , Code } from "@ninna-ui/primitives";
export default function Example() {
return (
Popover content here
);
}
```
### Tooltip
import { Tooltip } from "@ninna-ui/overlays";
Tooltip props:
- children (required): ReactNode — Tooltip content (Trigger, Content)
- open: boolean — Controlled open state
- defaultOpen: boolean [default: false] — Default open state (uncontrolled)
- onOpenChange: (open: boolean) => void — Callback when open state changes
- delayDuration: number [default: 200] — Delay in ms before showing the tooltip
- disableHoverableContent: boolean [default: false] — Whether to disable hoverable content
Content props:
- side: 'top' | 'right' | 'bottom' | 'left' [default: 'top'] — Which side to place the tooltip
- sideOffset: number [default: 4] — Distance from trigger in pixels
- align: 'start' | 'center' | 'end' [default: 'center'] — Alignment along the side
- hasArrow: boolean [default: false] — Whether to show an arrow pointer
- avoidCollisions: boolean [default: true] — Whether to avoid collisions with viewport boundary
- className: string — Additional CSS classes
Trigger props:
- asChild: boolean [default: false] — Render as child element instead of wrapping button
Example:
```tsx
import { Tooltip } from "@ninna-ui/overlays";
import { Button , Code } from "@ninna-ui/primitives";
export default function Example() {
return (
Tooltip text
);
}
```
======================================================
@ninna-ui/navigation
======================================================
### Accordion
import { Accordion } from "@ninna-ui/navigation";
Accordion props:
- type (required): 'single' | 'multiple' — Whether one or many items can be open at once
- variant: 'outline' | 'soft' | 'ghost' [default: 'outline'] — Visual style variant
- value: string | string[] — Controlled open item(s)
- defaultValue: string | string[] — Default open item(s) (uncontrolled)
- onValueChange: (value: string | string[]) => void — Callback when open items change
- collapsible: boolean [default: false] — Allow all items to close (single mode only)
- className: string — Additional CSS classes
Item props:
- value (required): string — Unique value for this item
- disabled: boolean [default: false] — Whether the item is disabled
Content props:
- forceMount: true — Whether to force mount the content (keeps DOM alive)
Example:
```tsx
import { Accordion } from "@ninna-ui/navigation";
export default function Example() {
return (
Question 1Answer 1Question 2Answer 2
);
}
```
### Breadcrumbs
import { Breadcrumbs } from "@ninna-ui/navigation";
Breadcrumbs props:
- separator: ReactNode [default: '/'] — Custom separator between items
- maxItems: number — Maximum number of visible items before collapsing
- size: 'sm' | 'md' | 'lg' [default: 'md'] — Size of the breadcrumbs
- className: string — Additional CSS classes
Link props:
- current: boolean [default: false] — Whether this is the current/active page
- icon: ReactNode — Icon element to render before the link text
- href: string — Link destination URL
Example:
```tsx
import { Breadcrumbs } from "@ninna-ui/navigation";
export default function Example() {
return (
HomePage
);
}
```
### Pagination
import { Pagination } from "@ninna-ui/navigation";
Pagination props:
- size: 'sm' | 'md' | 'lg' [default: 'md'] — Size of the pagination
- className: string — Additional CSS classes
Link props:
- isActive: boolean [default: false] — Whether this is the active/current page
- size: 'sm' | 'md' | 'lg' [default: 'md'] — Size variant
Example:
```tsx
import { Pagination } from "@ninna-ui/navigation";
export default function Example() {
return (
123
);
}
```
### Stepper
import { Stepper } from "@ninna-ui/navigation";
Stepper props:
- activeStep (required): number — Current active step index (0-based)
- orientation: 'horizontal' | 'vertical' [default: 'horizontal'] — Orientation of the stepper
- size: 'sm' | 'md' | 'lg' [default: 'md'] — Size of the stepper
- color: 'primary' | 'secondary' | 'accent' | 'neutral' | 'success' | 'danger' | 'warning' | 'info' [default: 'primary'] — Color theme of the stepper
- aria-label: string [default: 'Progress'] — Accessible label for the stepper list
- className: string — Additional CSS classes
Step props:
- label (required): string — Step label text
- description: string — Optional step description
- icon: ReactNode — Optional custom icon
- optional: boolean [default: false] — Whether the step is optional
Example:
```tsx
import { Stepper } from "@ninna-ui/navigation";
export default function Example() {
return (
);
}
```
### Tabs
import { Tabs } from "@ninna-ui/navigation";
Tabs props:
- value: string — Controlled active tab value
- defaultValue: string — Default active tab value (uncontrolled)
- onValueChange: (value: string) => void — Callback when active tab changes
- orientation: 'horizontal' | 'vertical' [default: 'horizontal'] — Orientation of the tabs
- activationMode: 'automatic' | 'manual' [default: 'automatic'] — Whether keyboard activation is automatic
- className: string — Additional CSS classes
List props:
- variant: 'line' | 'enclosed' | 'soft' | 'outline' [default: 'line'] — Visual style variant
- size: 'sm' | 'md' | 'lg' [default: 'md'] — Size of the tab triggers
- loop: boolean [default: true] — Whether to loop keyboard navigation
Trigger props:
- value (required): string — Value that associates the trigger with a content panel
- disabled: boolean [default: false] — Whether the trigger is disabled
Content props:
- value (required): string — Value that associates the content with a trigger
- forceMount: true — Whether to force mount the content (keeps DOM alive)
Example:
```tsx
import { Tabs } from "@ninna-ui/navigation";
export default function Example() {
return (
AccountSettingsAccount contentSettings content
);
}
```
======================================================
@ninna-ui/data-display
======================================================
### Calendar
import { Calendar } from "@ninna-ui/data-display";
Calendar props:
- aria-label: string [default: 'Calendar'] — Accessible label for the calendar widget
- value: Date — Selected date (controlled)
- defaultValue: Date — Default selected date (uncontrolled)
- onValueChange: (date: Date) => void — Callback when selected date changes
- minDate: Date — Minimum selectable date
- maxDate: Date — Maximum selectable date
- disabledDates: Date[] — Array of dates to disable
- showOutsideDays: boolean [default: true] — Show days from adjacent months
- weekStartsOn: 0 | 1 [default: 0] — First day of week (0=Sunday, 1=Monday)
- className: string — Additional CSS classes
Example:
```tsx
import { Calendar } from "@ninna-ui/data-display";
export default function Example() {
return (
);
}
```
### Card
import { Card } from "@ninna-ui/data-display";
Card props:
- variant: 'outline' | 'elevated' | 'filled' | 'ghost' | 'soft' | 'solid' [default: 'outline'] — Visual style variant
- color: 'primary' | 'secondary' | 'accent' | 'neutral' | 'success' | 'danger' | 'warning' | 'info' — Color theme of the card
- interactive: boolean [default: false] — Enable hover and focus styles for clickable cards
- className: string — Additional CSS classes
Header props:
- className: string — Additional CSS classes
Title props:
- className: string — Additional CSS classes
Example:
```tsx
import { Card } from "@ninna-ui/data-display";
import { Button } from "@ninna-ui/primitives";
export default function Example() {
return (
TitleDescriptionContent here
);
}
```
### DataTable
import { DataTable } from "@ninna-ui/data-display";
Datatable props:
- aria-label: string — Accessible label for the table element (recommended for screen readers)
- data (required): T[] — Array of row data
- columns (required): DataTableColumn[] — Column definitions
- rowKey (required): keyof T — Unique key field for rows
- striped: boolean [default: false] — Alternating row background colors
- compact: boolean [default: false] — Reduced cell padding
- bordered: boolean [default: false] — Show cell borders
- loading: boolean [default: false] — Show loading overlay
- emptyMessage: ReactNode — Message when data array is empty
- caption: string — Accessible table caption
- onSort: (state: SortState) => void — Callback when sort changes
- className: string — Additional CSS classes
Column props:
- id (required): string — Unique column identifier
- header (required): string | ReactNode — Column header content
- accessorKey: keyof T — Key to access row data
- cell: (row: T) => ReactNode — Custom cell renderer
- sortable: boolean [default: false] — Whether the column is sortable
Example:
```tsx
import { DataTable } from "@ninna-ui/data-display";
const columns = [
{ id: "name", header: "Name", accessorKey: "name", sortable: true },
{ id: "email", header: "Email", accessorKey: "email" },
];
export default function Example() {
return ;
}
```
### Stat
import { Stat } from "@ninna-ui/data-display";
Value props:
- size: 'sm' | 'md' | 'lg' [default: 'md'] — Size of the value text
- className: string — Additional CSS classes
Trend props:
- direction (required): 'up' | 'down' | 'neutral' — Trend direction
- positiveIsGood: boolean [default: true] — Whether up direction uses positive (green) color
- className: string — Additional CSS classes
Example:
```tsx
import { Stat } from "@ninna-ui/data-display";
export default function Example() {
return (
Revenue$45,231+20.1%
);
}
```
### Table
import { Table } from "@ninna-ui/data-display";
Table props:
- children (required): ReactNode — Table sub-components (Header, Body, Footer, Caption)
- className: string — Additional CSS classes
Row props:
- children (required): ReactNode — Row cells (Head or Cell)
- className: string — Additional CSS classes
Head props:
- children: ReactNode — Header cell content
- className: string — Additional CSS classes
Cell props:
- children: ReactNode — Cell content
- className: string — Additional CSS classes
Caption props:
- children (required): ReactNode — Caption text
- className: string — Additional CSS classes
Example:
```tsx
import { Table } from "@ninna-ui/data-display";
export default function Example() {
return (
NameEmailAlicealice@example.com
);
}
```
### Timeline
import { Timeline } from "@ninna-ui/data-display";
Indicator props:
- status: 'primary' | 'success' | 'danger' | 'warning' — Color variant for the indicator dot
- icon: ReactNode — Custom icon to replace the default dot
Example:
```tsx
import { Timeline } from "@ninna-ui/data-display";
export default function Example() {
return (
Event TitleDetails hereJan 1, 2024
);
}
```
### Tree
import { Tree } from "@ninna-ui/data-display";
Tree props:
- aria-label: string — Accessible label for the tree widget (use when no visible label exists)
- aria-labelledby: string — ID of an element that labels the tree
- data (required): TreeNode[] — Tree data structure
- selectedId: string — Currently selected node id
- onSelect: (id: string) => void — Callback when a node is selected
- defaultExpandedIds: string[] — Initially expanded node ids
- showLines: boolean [default: true] — Show connecting lines between nodes
- showIcons: boolean [default: true] — Show folder/file icons
- className: string — Additional CSS classes
Node props:
- id (required): string — Unique node identifier
- label (required): string — Display label for the node
- children: TreeNode[] — Child nodes (makes this a folder)
- icon: ReactNode — Custom icon for the node
- disabled: boolean — Whether the node is interaction-disabled
Example:
```tsx
import { Tree } from "@ninna-ui/data-display";
const data = [
{ id: "1", label: "Folder", children: [
{ id: "1-1", label: "File.tsx" },
]},
];
export default function Example() {
return ;
}
```
======================================================
Package: @ninna-ui/core
======================================================
### File: @ninna-ui/core/dist/index.d.ts (published types)
```ts
/**
* Color Design Tokens
* Semantic color names used throughout the design system
*/
/**
* Primary semantic colors for components
* Maps to CSS custom properties in theme presets
*/
type Color = 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'danger';
/**
* All available color values as a readonly array
* Useful for iteration and validation
*/
declare const COLORS: readonly ["neutral", "primary", "secondary", "accent", "info", "success", "warning", "danger"];
/**
* Typography Design Tokens
* Text size, weight, and semantic element types
*/
/** Text size scale */
type TextSize = 'base' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl';
/** Font weight options */
type TextWeight = 'light' | 'normal' | 'medium' | 'semibold' | 'bold';
/** Semantic text element types */
type TextAs = 'p' | 'span' | 'div' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
/** Heading level types */
type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
/**
* Border Radius Design Tokens
* Corner radius scale for components
*/
/** Border radius options */
type Radius = 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
/**
* Size Design Tokens
* Component size scale
*/
/** Standard component size scale */
type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
/** Compact size scale for selectors - Checkbox, Radio, Switch, Slider */
type CompactSize = Extract;
/** Extended spinner size scale */
type SpinnerSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
/**
* Component Variant Design Tokens
* Style variants for interactive components
*/
/**
* Color variants for visual components - Badge, Alert, Toast, Checkbox, Radio, Switch
* - solid: Filled background with contrasting text
* - soft: Light tinted background with colored text
* - outline: Transparent with colored border
*/
type ColorVariant = 'solid' | 'soft' | 'outline';
/**
* Button/IconButton style variants - extends ColorVariant with ghost + text
* - ghost: No background, subtle hover
* - text: Just colored text with underline on hover
*/
type ButtonVariant = ColorVariant | 'ghost' | 'text';
/**
* Form input visual variants - Input, Textarea, Select, NumberInput
* - outline: Border with transparent background
* - filled: Filled background, transparent border
* - flushed: Bottom-border only, no rounded corners
* - unstyled: No visual styling, bare input
*/
type InputVariant = 'outline' | 'filled' | 'flushed' | 'unstyled';
/**
* Layout Design Tokens
* Spacing, grid, and flex type definitions shared across layout components
*/
/**
* Breakpoint keys for responsive props.
* Maps to Tailwind's default breakpoint scale.
*/
type Breakpoint = 'base' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
/**
* A single value or a responsive object keyed by breakpoint.
* Allows components to accept both simple and responsive values:
*
* @example
* columns={3} // fixed
* columns={{ base: 1, md: 2, lg: 3 }} // responsive
*/
type ResponsiveValue = T | Partial>;
/** Gap size options (spacing scale) */
type GapSize = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12' | '14' | '16' | '20' | '24';
/** Grid columns options */
type GridColumns = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 'none';
/** Grid rows options */
type GridRows = 1 | 2 | 3 | 4 | 5 | 6 | 'none';
/** Grid flow options */
type GridFlow = 'row' | 'column' | 'dense' | 'row-dense' | 'column-dense';
/** Stack/Flex direction options */
type FlexDirection = 'row' | 'column' | 'row-reverse' | 'column-reverse';
/** Flex/Stack alignment options (cross-axis) */
type FlexAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
/** Flex/Stack justify options (main-axis) */
type FlexJustify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
/** Flex wrap options */
type FlexWrap = 'wrap' | 'nowrap' | 'wrap-reverse';
/** Container max width options */
type ContainerMaxWidth = 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full' | 'none';
/** Separator orientation options */
type SeparatorOrientation = 'horizontal' | 'vertical';
/** Aspect ratio preset options */
type AspectRatioPreset = 'square' | 'video' | 'portrait' | 'wide';
/**
* Base Color Class Mappings
* Direct color utility classes for backgrounds, text, borders, etc.
*/
/** Background color classes */
declare const BG_COLORS: Record;
/** Text color classes */
declare const TEXT_COLORS: Record;
/** Border color classes */
declare const BORDER_COLORS: Record;
/** Stroke color classes (for SVG elements) */
declare const STROKE_COLORS: Record;
/** Marker colors (for list items) */
declare const MARKER_COLORS: Record;
/**
* Layout Class Mappings
* Shared gap, grid, and flex Tailwind class mappings
*/
/** Gap size class mappings */
declare const GAP_SIZES: Record;
/** Row gap size class mappings */
declare const ROW_GAP_SIZES: Record;
/** Column gap size class mappings */
declare const COLUMN_GAP_SIZES: Record;
/** Grid columns class mappings */
declare const GRID_COLUMNS: Record;
/**
* Responsive grid columns — prefix each column class with a breakpoint.
* Used internally by Grid's responsive `columns` prop.
*
* Accepts either a fixed `GridColumns` value or a `ResponsiveValue`
* breakpoint map.
*
* @example getResponsiveGridCols({ base: 1, md: 2, lg: 4 })
* // → 'grid-cols-1 md:grid-cols-2 lg:grid-cols-4'
*/
declare function getResponsiveGridCols(value: ResponsiveValue): string;
/** Grid rows class mappings */
declare const GRID_ROWS: Record;
/** Flex direction class mappings */
declare const FLEX_DIRECTION: Record;
/** Flex align-items class mappings */
declare const FLEX_ALIGN: Record;
/** Flex justify-content class mappings */
declare const FLEX_JUSTIFY: Record;
/** Flex wrap class mappings */
declare const FLEX_WRAP: Record;
export { type AspectRatioPreset, BG_COLORS, BORDER_COLORS, type Breakpoint, type ButtonVariant, COLORS, COLUMN_GAP_SIZES, type Color, type ColorVariant, type CompactSize, type ContainerMaxWidth, FLEX_ALIGN, FLEX_DIRECTION, FLEX_JUSTIFY, FLEX_WRAP, type FlexAlign, type FlexDirection, type FlexJustify, type FlexWrap, GAP_SIZES, GRID_COLUMNS, GRID_ROWS, type GapSize, type GridColumns, type GridFlow, type GridRows, type HeadingLevel, type InputVariant, MARKER_COLORS, ROW_GAP_SIZES, type Radius, type ResponsiveValue, STROKE_COLORS, type SeparatorOrientation, type Size, type SpinnerSize, TEXT_COLORS, type TextAs, type TextSize, type TextWeight, getResponsiveGridCols };
```
======================================================
Package: @ninna-ui/primitives
======================================================
### File: @ninna-ui/primitives/dist/index.d.ts (published types)
```ts
import * as react from 'react';
import { ButtonHTMLAttributes, ReactNode, HTMLAttributes, ImgHTMLAttributes, AnchorHTMLAttributes, BlockquoteHTMLAttributes, LiHTMLAttributes } from 'react';
import { ButtonVariant, Color, Size, Radius, ColorVariant, TextSize, TextWeight, HeadingLevel } from '@ninna-ui/core';
interface ButtonProps extends ButtonHTMLAttributes {
/** Visual style variant */
variant?: ButtonVariant;
/** Color theme */
color?: Color;
/** Size of the button */
size?: Size;
/** Border radius style */
radius?: Radius;
/** Whether the button is in a loading state */
loading?: boolean;
/** Whether to make the button full width */
fullWidth?: boolean;
/** Icon to display on the left */
leftIcon?: ReactNode;
/** Icon to display on the right */
rightIcon?: ReactNode;
}
/**
* Button component with multiple variants, sizes, and states.
*
* @example
* ```tsx
*
*
* }>With Icon
*
* ```
*/
declare const Button: react.ForwardRefExoticComponent>;
/** Badge variant - uses core ColorVariant for consistency */
type BadgeVariant = ColorVariant;
/**
* Badge props interface
*/
interface BadgeProps extends HTMLAttributes {
/** Visual style variant */
variant?: BadgeVariant;
/** Color theme */
color?: Color;
/** Size of the badge
* @default 'md'
*/
size?: Size;
/** Border radius style */
radius?: Radius;
/** Content to display */
children?: ReactNode;
}
/**
* Badge component for status indicators, labels, and tags.
*
* @example
* ```tsx
* New
* Active
* 3
* ```
*/
declare const Badge: react.ForwardRefExoticComponent>;
type DividerVariant = "horizontal" | "vertical" | "with-text";
type DividerWeight = "soft" | "solid";
interface DividerProps extends HTMLAttributes {
/** Orientation and style variant */
variant?: DividerVariant;
/** Color theme */
color?: Color;
/** Line weight/opacity */
weight?: DividerWeight;
/** Text to display (only for with-text variant) */
text?: string;
}
/**
* Divider component for visual separation
*
* @example
* ```tsx
*
*
*
* ```
*/
declare const Divider: react.ForwardRefExoticComponent>;
/** Avatar shape variants */
type AvatarShape = 'circle' | 'square';
interface AvatarProps extends HTMLAttributes {
/** Image source URL */
src?: string;
/** Alternative text for the image */
alt?: string;
/** Name used to generate initials fallback */
name?: string;
/** Size of the avatar */
size?: Size;
/** Shape of the avatar */
shape?: AvatarShape;
/** Border radius (only applies when shape is "square") */
radius?: Radius;
/** Color theme for fallback background */
color?: Color;
/** Show a colored ring around the avatar */
showRing?: boolean;
/** Ring color (defaults to color prop) */
ringColor?: Color;
/** Custom fallback content when image fails or no src */
fallback?: ReactNode;
/** Show fallback icon instead of initials */
showFallbackIcon?: boolean;
/** Image loading attribute */
loading?: ImgHTMLAttributes["loading"];
}
interface AvatarGroupProps extends HTMLAttributes {
/** Maximum number of avatars to show */
max?: number;
/** Size for all avatars in the group */
size?: Size;
/** Spacing between avatars (negative for overlap) */
spacing?: 'tight' | 'normal' | 'loose';
/** Avatar children */
children: ReactNode;
}
/**
* Avatar component for displaying user profile pictures or initials.
* Pure UI component - no internal state management.
*
* @example
* ```tsx
*
*
*
* ```
*/
declare const Avatar: react.ForwardRefExoticComponent>;
/**
* AvatarGroup component for displaying multiple avatars with overlap.
*
* @example
* ```tsx
*
*
*
*
*
*
* ```
*/
declare const AvatarGroup: react.ForwardRefExoticComponent>;
interface IconButtonProps extends ButtonHTMLAttributes {
/** The icon to display */
icon: ReactNode;
/** Visual style variant */
variant?: ButtonVariant;
/** Color theme */
color?: Color;
/** Size of the button */
size?: Size;
/** Border radius style */
radius?: Radius;
/** Whether the button is in a loading state */
loading?: boolean;
/** Accessible label for the button (required for accessibility) */
"aria-label": string;
}
declare const IconButton: react.ForwardRefExoticComponent>;
type TextAlign = 'left' | 'center' | 'right' | 'justify';
interface TextProps extends HTMLAttributes {
/** The HTML element to render */
as?: 'p' | 'span' | 'div' | 'label' | 'strong' | 'em' | 'small' | 'mark' | 'del' | 'ins' | 'sub' | 'sup';
/** Text size */
size?: TextSize;
/** Font weight */
weight?: TextWeight;
/** Text color */
color?: Color;
/** Text alignment */
align?: TextAlign;
/** Whether to truncate text with ellipsis */
truncate?: boolean;
/** Maximum number of lines before truncating (requires truncate) */
lineClamp?: 1 | 2 | 3 | 4 | 5 | 6;
/** Whether to use muted/secondary text color */
muted?: boolean;
/** Whether text should not wrap */
noWrap?: boolean;
/** Whether to transform text to uppercase */
uppercase?: boolean;
/** Whether to transform text to lowercase */
lowercase?: boolean;
/** Whether to capitalize text */
capitalize?: boolean;
/** Whether to apply italic style */
italic?: boolean;
/** Whether to apply underline */
underline?: boolean;
/** Whether to apply line-through (strikethrough) */
strikethrough?: boolean;
}
/**
* Text component for rendering typography with various styles.
*
* @example
* ```tsx
* Default text
* Large bold text
* Primary colored text
* This text will be truncated...
* Muted span text
* ```
*/
declare const Text: react.ForwardRefExoticComponent>;
type HeadingAlign = 'left' | 'center' | 'right';
interface HeadingProps extends HTMLAttributes {
/** The heading level (h1-h6) - determines semantic HTML element */
as?: HeadingLevel;
/** Override the default size for the heading level */
size?: TextSize;
/** Font weight override */
weight?: TextWeight;
/** Text color */
color?: Color;
/** Text alignment */
align?: HeadingAlign;
/** Whether to truncate text with ellipsis */
truncate?: boolean;
/** Maximum number of lines before truncating */
lineClamp?: 1 | 2 | 3 | 4 | 5 | 6;
/** Whether text should not wrap */
noWrap?: boolean;
}
/**
* Heading component for rendering semantic headings (h1-h6) with various styles.
*
* @example
* ```tsx
* Page Title
* Section Title
* Colored Heading
* Light Weight Heading
* ```
*/
declare const Heading: react.ForwardRefExoticComponent>;
type LinkUnderline = 'always' | 'hover' | 'none';
interface LinkProps extends AnchorHTMLAttributes {
/** Text size - matches Text component sizes */
size?: TextSize;
/** Color variant */
color?: Color;
/** Underline behavior */
underline?: LinkUnderline;
/** Whether the link opens in a new tab (adds target="_blank" and rel="noopener noreferrer") */
external?: boolean;
/** Whether to show an external link icon */
showExternalIcon?: boolean;
/** Custom external icon */
externalIcon?: ReactNode;
}
/**
* Link component for rendering accessible anchor elements with various styles.
*
* @example
* ```tsx
* About
* External Link
* Documentation
* ```
*/
declare const Link: react.ForwardRefExoticComponent>;
interface LinkOverlayProps extends AnchorHTMLAttributes {
/** Whether the link opens in a new tab */
external?: boolean;
}
interface LinkBoxProps extends React.HTMLAttributes {
/** The HTML element to render as */
as?: 'div' | 'article' | 'section' | 'aside' | 'header' | 'footer' | 'main' | 'nav';
}
/**
* LinkBox component - A container that makes the entire area clickable via LinkOverlay.
* Use this to wrap content that should be clickable as a single unit.
*
* @example
* ```tsx
*
*
* Article Title
*
* Article description...
* Author Name
*
* ```
*/
declare const LinkBox: react.ForwardRefExoticComponent>;
/**
* LinkOverlay component - Stretches to cover the entire LinkBox, making it clickable.
* Place this inside a LinkBox to make the entire box clickable.
*
* @example
* ```tsx
*
*
* Clickable Heading
*
*
* ```
*/
declare const LinkOverlay: react.ForwardRefExoticComponent>;
interface CodeProps extends HTMLAttributes {
/** Color variant */
color?: Color;
/** Text size */
size?: TextSize;
}
/**
* Code component for rendering inline code snippets with various styles.
*
* @example
* ```tsx
* npm install
* const x = 1
* function hello()
* ```
*/
declare const Code: react.ForwardRefExoticComponent>;
type BlockquoteVariant = ColorVariant;
interface BlockquoteProps extends BlockquoteHTMLAttributes {
/** Color variant */
color?: Color;
/** Visual style variant */
variant?: BlockquoteVariant;
/** Citation source */
cite?: string;
/** Citation author/source to display */
citeSource?: ReactNode;
/** Whether to show quote icon */
showIcon?: boolean;
/** Custom icon */
icon?: ReactNode;
}
/**
* Blockquote component for rendering styled quotations with optional citation.
*
* @example
* ```tsx
*
This is a quote
*
Styled quote
*
Quote with citation
* ```
*/
declare const Blockquote: react.ForwardRefExoticComponent>;
type ListType = "unordered" | "ordered";
type ListSpacing = "none" | "sm" | "md" | "lg";
type ListMarker = "disc" | "circle" | "square" | "decimal" | "alpha" | "roman" | "none" | "check" | "arrow";
interface ListProps extends HTMLAttributes {
/** List type */
type?: ListType;
/** Spacing between items */
spacing?: ListSpacing;
/** Marker style */
marker?: ListMarker;
/** Marker color */
markerColor?: Color;
/** Whether to use custom icon markers */
icon?: ReactNode;
}
interface ListItemProps extends LiHTMLAttributes {
/** Custom icon for this item */
icon?: ReactNode;
/** Icon color for this item */
iconColor?: Color;
}
/**
* List component for rendering styled ordered and unordered lists.
*
* @example
* ```tsx
*
* Item 1
* Item 2
*
*
*
* First
* Second
*
*
*
* Completed task
*
* ```
*/
declare const List: react.ForwardRefExoticComponent>;
/**
* ListItem component for rendering individual list items.
*
* @example
* ```tsx
* Basic item
* }>Item with custom icon
* ```
*/
declare const ListItem: react.ForwardRefExoticComponent>;
/**
* Kbd size type
*/
type KbdSize = Extract;
/**
* Props for the Kbd component
*/
interface KbdProps extends HTMLAttributes {
/**
* Color variant
* @default "neutral"
*/
color?: Color;
/**
* Size variant
* @default "sm"
*/
size?: KbdSize;
}
/**
* Kbd component for displaying keyboard keys or shortcuts.
*
* @example
* ```tsx
* ⌘
* Ctrl + C
* Enter
* ```
*/
declare const Kbd: react.ForwardRefExoticComponent>;
/**
* Props for the Mark component
*/
interface MarkProps extends HTMLAttributes {
/**
* Color variant
* @default "neutral"
*/
color?: Color;
}
/**
* Mark component for highlighting text.
*
* @example
* ```tsx
* highlighted text
* primary highlight
* success highlight
* ```
*/
declare const Mark: react.ForwardRefExoticComponent>;
export { Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarShape, Badge, type BadgeProps, type BadgeVariant, Blockquote, type BlockquoteProps, type BlockquoteVariant, Button, type ButtonProps, Code, type CodeProps, Divider, type DividerProps, type DividerVariant, type DividerWeight, Heading, type HeadingAlign, type HeadingProps, IconButton, type IconButtonProps, Kbd, type KbdProps, type KbdSize, Link, LinkBox, type LinkBoxProps, LinkOverlay, type LinkOverlayProps, type LinkProps, type LinkUnderline, List, ListItem, type ListItemProps, type ListMarker, type ListProps, type ListSpacing, type ListType, Mark, type MarkProps, Text, type TextAlign, type TextProps };
```
======================================================
Package: @ninna-ui/feedback
======================================================
### File: @ninna-ui/feedback/dist/index.d.ts (published types)
```ts
import * as react from 'react';
import react__default, { HTMLAttributes, ReactNode } from 'react';
import { Color, SpinnerSize, ColorVariant, Size, CompactSize, Radius } from '@ninna-ui/core';
import * as react_jsx_runtime from 'react/jsx-runtime';
type LoadingVariant = "spin" | "ping" | "pulse" | "dots";
interface LoadingProps extends HTMLAttributes {
/** Visual style variant */
variant?: LoadingVariant;
/** Color theme */
color?: Color;
/** Size of the loading indicator */
size?: SpinnerSize;
/** Accessible label for screen readers */
label?: string;
}
/**
* Loading component for loading states
*
* @example
*
*
*
*/
declare const Loading: react.ForwardRefExoticComponent>;
type AlertVariant = ColorVariant;
interface AlertProps extends Omit, "title"> {
/** Visual style variant */
variant?: AlertVariant;
/** Color theme */
color?: Color;
/** Alert title */
title?: ReactNode;
/** Alert description/message */
description?: ReactNode;
/** Custom icon to display */
icon?: ReactNode;
/** Whether to show the default icon based on color */
showIcon?: boolean;
/** Whether the alert can be dismissed */
dismissible?: boolean;
/** Callback when alert is dismissed */
onDismiss?: () => void;
/** Size of the alert */
size?: Size;
/** Action element (button, link, etc.) */
action?: ReactNode;
/** Additional CSS classes */
className?: string;
/** Alert content (alternative to description) */
children?: ReactNode;
}
/**
* Alert component for displaying important messages
*
* @example
* ```tsx
*
* {}}>
* Something went wrong. Please try again.
*
* Retry}>
* Your session is about to expire.
*
* ```
*/
declare const Alert: react__default.ForwardRefExoticComponent>;
type ProgressVariant = "default" | "striped" | "animated";
type ProgressLabelPosition = "left" | "right" | "top" | "inside" | "none";
interface ProgressProps extends Omit, "children"> {
/** Current progress value (0-100 or custom max) */
value?: number;
/** Maximum value */
max?: number;
/** Size of the progress bar */
size?: Size;
/** Color theme */
color?: Color;
/** Visual style variant */
variant?: ProgressVariant;
/** Whether to show the value label */
showValue?: boolean;
/** Position of the value label */
labelPosition?: ProgressLabelPosition;
/** Custom format function for the value label */
formatLabel?: (value: number, max: number) => ReactNode;
/** Whether the progress is indeterminate (loading state) */
indeterminate?: boolean;
/** Accessible label for screen readers */
label?: string;
/** Additional CSS classes */
className?: string;
/** Additional CSS classes for the track (background) */
trackClassName?: string;
/** Additional CSS classes for the indicator (filled part) */
indicatorClassName?: string;
}
/**
* Progress component for displaying progress indicators
*
* @example
* ```tsx
*
*
*
*
* ```
*/
declare const Progress: react.ForwardRefExoticComponent>;
type CircularProgressLabelPosition = "center" | "bottom" | "none";
interface CircularProgressProps extends Omit, "children"> {
/** Current progress value (0-100 or custom max) */
value?: number;
/** Maximum value */
max?: number;
/** Size of the circular progress */
size?: Size;
/** Color theme */
color?: Color;
/** Stroke width of the progress circle */
strokeWidth?: number;
/** Whether to show the value label */
showValue?: boolean;
/** Position of the value label */
labelPosition?: CircularProgressLabelPosition;
/** Custom format function for the value label */
formatLabel?: (value: number, max: number) => ReactNode;
/** Whether the progress is indeterminate (loading state) */
indeterminate?: boolean;
/** Accessible label for screen readers */
label?: string;
/** Additional CSS classes */
className?: string;
/** Additional CSS classes for the track (background circle) */
trackClassName?: string;
/** Additional CSS classes for the indicator (progress circle) */
indicatorClassName?: string;
/** Custom content to render inside the circle */
children?: ReactNode;
}
/**
* CircularProgress component for displaying circular progress indicators
*
* @example
* ```tsx
*
*
*
* ```
*/
declare const CircularProgress: react.ForwardRefExoticComponent>;
/** Status value options */
type StatusValue = 'success' | 'danger' | 'warning' | 'info';
/** Status size - uses core CompactSize for consistency */
type StatusSize = CompactSize;
/**
* Props for the Status component
*/
interface StatusProps extends HTMLAttributes {
/**
* Status value that determines the color
* @default "info"
*/
value?: StatusValue;
/**
* Size of the status indicator
* @default "md"
*/
size?: StatusSize;
/**
* Label text to display next to the indicator
*/
children?: ReactNode;
}
/**
* Status component for displaying status indicators with optional labels.
* Used to indicate the status of a process or state.
*
* @example
* ```tsx
* Completed
* Failed
* Pending
* Processing
* ```
*/
declare const Status: react.ForwardRefExoticComponent>;
/** Skeleton animation variant options */
type SkeletonVariant = 'pulse' | 'shine' | 'none';
/**
* Props for the Skeleton component
*/
interface SkeletonProps extends HTMLAttributes {
/**
* Animation variant
* @default "pulse"
*/
variant?: SkeletonVariant;
/**
* Width of the skeleton
*/
width?: string | number;
/**
* Height of the skeleton
*/
height?: string | number;
/**
* Border radius
* @default "md"
*/
radius?: Radius;
/**
* Whether the skeleton is loading
* @default true
*/
loading?: boolean;
/**
* Content to show when not loading
*/
children?: ReactNode;
}
/**
* Props for the SkeletonCircle component
*/
interface SkeletonCircleProps extends Omit {
/**
* Size of the circle (width and height)
* @default "40px"
*/
size?: string | number;
}
/**
* Props for the SkeletonText component
*/
interface SkeletonTextProps extends HTMLAttributes {
/**
* Number of lines to render
* @default 3
*/
noOfLines?: number;
/**
* Gap between lines
* @default "8px"
*/
gap?: string | number;
/**
* Animation variant
* @default "pulse"
*/
variant?: SkeletonVariant;
/**
* Whether the skeleton is loading
* @default true
*/
loading?: boolean;
/**
* Content to show when not loading
*/
children?: ReactNode;
}
/**
* Skeleton component for displaying loading placeholders.
* Used to indicate content is loading.
*
* @example
* ```tsx
*
*
*
Content loaded
*
* ```
*/
declare const Skeleton: react.ForwardRefExoticComponent>;
/**
* SkeletonCircle component for circular loading placeholders.
* Commonly used for avatar placeholders.
*
* @example
* ```tsx
*
*
* ```
*/
declare const SkeletonCircle: react.ForwardRefExoticComponent>;
/**
* SkeletonText component for text loading placeholders.
* Renders multiple lines to simulate text content.
*
* @example
* ```tsx
*
*
* ```
*/
declare const SkeletonText: react.ForwardRefExoticComponent>;
/** EmptyState size options */
type EmptyStateSize = 'sm' | 'md' | 'lg';
/**
* Props for the EmptyState component
*/
interface EmptyStateProps extends HTMLAttributes {
/**
* Title text
*/
title: string;
/**
* Description text
*/
description?: string;
/**
* Icon to display
*/
icon?: ReactNode;
/**
* Size of the empty state
* @default "md"
*/
size?: EmptyStateSize;
/**
* Action button or content
*/
action?: ReactNode;
/**
* Additional content below the description
*/
children?: ReactNode;
}
/**
* EmptyState component for displaying empty or unavailable resource states.
* Used to indicate when there is no data to display.
*
* @example
* ```tsx
* }
* action={}
* />
* ```
*/
declare const EmptyState: react.ForwardRefExoticComponent>;
/** Toast position on screen */
type ToastPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
/** Toast variant - uses core ColorVariant for consistency */
type ToastVariant = ColorVariant;
/** Toast data structure for creating toasts */
interface ToastData {
/** Unique identifier for the toast */
id: string;
/** Toast title */
title?: ReactNode;
/** Toast description/message */
description?: ReactNode;
/** Color theme */
color?: Color;
/** Visual variant */
variant?: ToastVariant;
/** Show a spinning loading indicator. Use with duration: 0 to keep the toast persistent until updated. */
isLoading?: boolean;
/** Duration in milliseconds (0 = persistent) */
duration?: number;
/** Whether the toast can be dismissed */
closable?: boolean;
/** Custom icon */
icon?: ReactNode;
/** Action button configuration */
action?: {
label: string;
onClick: () => void;
altText?: string;
};
/** Callback when toast is closed */
onClose?: () => void;
/** Callback when toast opens */
onOpen?: () => void;
/** Route this toast to a specific Toaster by its id */
toasterId?: string;
}
/** Props for creating a new toast */
type CreateToastOptions = Omit;
/** Toast component props */
interface ToastProps {
/** Toast data */
toast: ToastData;
/** Callback to dismiss the toast */
onDismiss?: (id: string) => void;
/** Position of the toaster - used for correct enter/exit animations */
position?: ToastPosition;
/** Additional CSS classes */
className?: string;
}
/** Toaster provider props */
interface ToasterProps {
/** Position of toasts on screen */
position?: ToastPosition;
/** Maximum number of visible toasts */
max?: number;
/** Gap between toasts */
gap?: number;
/** Offset from screen edges */
offset?: string | number;
/** Pause auto-dismiss on hover */
pauseOnHover?: boolean;
/** Unique id - only toasts created with this toasterId will be shown */
id?: string;
/** Additional CSS classes for viewport */
className?: string;
/** Children (usually not needed) */
children?: ReactNode;
}
/** Toast context value */
interface ToastContextValue {
/** Create a new toast */
toast: (options: CreateToastOptions) => string;
/** Dismiss a toast by id, or all if no id provided */
dismiss: (id?: string) => void;
/** Dismiss all toasts */
dismissAll: () => void;
/** Update an existing toast */
update: (id: string, options: Partial) => void;
/** Promise-based toast - shows loading spinner, then success/error on resolution */
promise: (promise: Promise, options: {
loading: CreateToastOptions | string;
success: CreateToastOptions | string | ((data: T) => CreateToastOptions | string);
error: CreateToastOptions | string | ((error: unknown) => CreateToastOptions | string);
}) => Promise;
}
declare const Toast: react.ForwardRefExoticComponent>;
declare const toast: {
create: (options: CreateToastOptions) => string;
dismiss: (id?: string) => void;
dismissAll: () => void;
update: (id: string, options: Partial) => void;
promise: (promise: Promise, options: {
loading: CreateToastOptions | string;
success: CreateToastOptions | string | ((data: T) => CreateToastOptions | string);
error: CreateToastOptions | string | ((error: unknown) => CreateToastOptions | string);
}) => Promise;
};
declare const Toaster: react.ForwardRefExoticComponent>;
interface ToastProviderProps {
children: ReactNode;
}
declare function ToastProvider({ children }: ToastProviderProps): react_jsx_runtime.JSX.Element;
declare function useToast(): ToastContextValue;
export { Alert, type AlertProps, type AlertVariant, CircularProgress, type CircularProgressLabelPosition, type CircularProgressProps, type CreateToastOptions, EmptyState, type EmptyStateProps, Loading, type LoadingProps, type LoadingVariant, Progress, type ProgressLabelPosition, type ProgressProps, type ProgressVariant, Skeleton, SkeletonCircle, type SkeletonCircleProps, type SkeletonProps, SkeletonText, type SkeletonTextProps, Status, type StatusProps, type StatusSize, type StatusValue, Toast, type ToastContextValue, type ToastData, type ToastProps, ToastProvider, type ToastVariant, Toaster, type ToasterProps, toast, useToast };
```
======================================================
Package: @ninna-ui/forms
======================================================
### File: @ninna-ui/forms/dist/index.d.ts (published types)
```ts
import * as react from 'react';
import { HTMLAttributes, ReactNode, LabelHTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, ComponentPropsWithoutRef } from 'react';
import { Size, InputVariant, Color, CompactSize, ColorVariant } from '@ninna-ui/core';
import * as react_jsx_runtime from 'react/jsx-runtime';
/**
* FormControl context state shared between form components
*/
interface FormControlContextValue {
/** Unique ID for the form field */
id: string;
/** ID for the form label element */
labelId: string;
/** ID for the form message/description element */
messageId: string;
/** Whether the field is required */
isRequired: boolean;
/** Whether the field is invalid */
isInvalid: boolean;
/** Whether the field is disabled */
isDisabled: boolean;
/** Whether the field is read-only */
isReadOnly: boolean;
}
/**
* FormControl props
*/
interface FormControlProps extends HTMLAttributes {
/** Unique ID for the form field (auto-generated if not provided) */
id?: string;
/** Whether the field is required */
isRequired?: boolean;
/** Whether the field is invalid */
isInvalid?: boolean;
/** Whether the field is disabled */
isDisabled?: boolean;
/** Whether the field is read-only */
isReadOnly?: boolean;
/** Child components */
children: ReactNode;
}
/**
* Hook to access FormControl context
*/
declare function useFormControl(): FormControlContextValue | null;
/**
* Fields that `useFormControlProps` may inject from a surrounding
* ``. Kept in sync with `FormControlContextValue` — the hook
* always returns these keys (typed as optional) so consumers can read them
* without unsafe casts.
*/
interface FormControlDerivedProps {
id?: string;
disabled?: boolean;
readOnly?: boolean;
required?: boolean;
'aria-invalid'?: boolean;
'aria-required'?: boolean;
'aria-disabled'?: boolean;
'aria-describedby'?: string;
'aria-labelledby'?: string;
}
/**
* Hook to get form control props for an input element.
*
* Returns the original props merged with any fields derived from a
* surrounding ``. Context fields **win** over the user's raw
* props — that is the whole point of ``. Consumers should spread
* the result first and only override fields they must control themselves
* (e.g. a wrapped `onChange`, a computed `className`, etc.).
*/
declare function useFormControlProps>(props: T): T & FormControlDerivedProps;
/**
* FormControl provides context for form field components
*
* @example
* ```tsx
*
* Email
*
* Please enter a valid email
*
* ```
*/
declare const FormControl: react.ForwardRefExoticComponent>;
/**
* FormLabel props
*/
interface FormLabelProps extends LabelHTMLAttributes {
/** Size of the label text */
size?: Size;
/** Whether to show required indicator */
showRequired?: boolean;
/** Custom required indicator */
requiredIndicator?: React.ReactNode;
}
/**
* FormLabel renders an accessible label for form fields
*
* @example
* ```tsx
*
* Email
*
*
* ```
*/
declare const FormLabel: react.ForwardRefExoticComponent>;
/** Message type */
type FormMessageType = 'error' | 'success' | 'warning' | 'hint';
/**
* FormMessage props
*/
interface FormMessageProps extends HTMLAttributes {
/** Type of message */
type?: FormMessageType;
/** Size of the message text */
size?: Size;
}
/**
* FormMessage displays error, success, warning, or hint messages
*
* @example
* ```tsx
*
* Email
*
* Please enter a valid email
*
* ```
*/
declare const FormMessage: react.ForwardRefExoticComponent>;
/**
* Input props
*/
interface InputProps extends Omit, 'size'> {
/** Size of the input */
size?: Size;
/** Visual variant */
variant?: InputVariant;
/** Color theme for focus state */
color?: Color;
/** Whether the input has an error state */
invalid?: boolean;
/** Whether the input takes full width */
fullWidth?: boolean;
/** Show a clear button when input has value */
clearable?: boolean;
/** Callback when clear button is clicked */
onClear?: () => void;
/** Maximum character length (enables counter when showCounter is true) */
maxLength?: number;
/** Show character counter (requires maxLength) */
showCounter?: boolean;
/** Floating label text */
floatingLabel?: string;
}
/**
* Input component for text entry
*
* @example
* ```tsx
*
*
* setValue('')} />
*
*
* ```
*/
declare const Input: react.ForwardRefExoticComponent>;
/**
* Textarea props
*/
interface TextareaProps extends Omit, 'size'> {
/** Size of the textarea */
size?: Size;
/** Visual variant */
variant?: InputVariant;
/** Color theme for focus state */
color?: Color;
/** Whether the textarea has an error state */
invalid?: boolean;
/** Resize behavior */
resize?: 'none' | 'vertical' | 'horizontal' | 'both';
/** Whether the textarea takes full width */
fullWidth?: boolean;
/** Auto-resize textarea based on content */
autoResize?: boolean;
/** Minimum number of rows when autoResize is enabled */
minRows?: number;
/** Maximum number of rows when autoResize is enabled */
maxRows?: number;
/** Show character counter (requires maxLength) */
showCounter?: boolean;
}
/**
* Textarea component for multi-line text entry
*
* @example
* ```tsx
*
*
*
*
* ```
*/
declare const Textarea: react.ForwardRefExoticComponent>;
/**
* Shared form component types
* Derives from core types for consistency across the design system.
*/
/** Checkbox size options */
type CheckboxSize = CompactSize;
/** Switch size options */
type SwitchSize = CompactSize;
/** Radio size options */
type RadioSize = CompactSize;
/** Slider size options */
type SliderSize = CompactSize;
/** Checkbox variant styles */
type CheckboxVariant = 'solid' | 'soft' | 'outline';
/**
* Checkbox props
*/
interface CheckboxProps extends Omit, 'onChange' | 'size' | 'checked'> {
/** Size of the checkbox */
size?: CheckboxSize;
/** Color theme */
color?: Color;
/** Visual variant */
variant?: CheckboxVariant;
/** Whether the checkbox is checked */
checked?: boolean;
/** Default checked state (uncontrolled) */
defaultChecked?: boolean;
/** Callback when checked state changes */
onCheckedChange?: (checked: boolean) => void;
/** Whether the checkbox is disabled */
disabled?: boolean;
/** Whether the checkbox is required */
required?: boolean;
/** Whether the checkbox is in an invalid state */
invalid?: boolean;
/** Whether the checkbox is in indeterminate state */
indeterminate?: boolean;
/** Name for form submission */
name?: string;
/** Value for form submission */
value?: string;
/** Label text */
label?: ReactNode;
/**
* Description text
* @deprecated Use Field wrapper with FieldDescription instead for better accessibility
*/
description?: ReactNode;
/** Position of the label relative to checkbox */
labelPosition?: 'start' | 'end';
/** Custom check icon */
icon?: ReactNode;
/** Custom indeterminate icon */
indeterminateIcon?: ReactNode;
}
/**
* CheckboxGroup props
*/
interface CheckboxGroupProps extends Omit, 'defaultValue' | 'onChange' | 'dir'> {
/** Selected values */
value?: string[];
/** Default selected values (uncontrolled) */
defaultValue?: string[];
/** Callback when selection changes */
onValueChange?: (value: string[]) => void;
/** Whether the entire group is disabled */
disabled?: boolean;
/** Whether a selection is required */
required?: boolean;
/** Whether the group is in an invalid state */
invalid?: boolean;
/** Size for all checkboxes in the group */
size?: CheckboxSize;
/** Color for all checkboxes in the group */
color?: Color;
/** Variant for all checkboxes in the group */
variant?: CheckboxVariant;
/** Orientation of the group */
orientation?: 'horizontal' | 'vertical';
/** Gap between items */
gap?: 'sm' | 'md' | 'lg';
/** Children (CheckboxGroupItem components) */
children: ReactNode;
/** Additional CSS classes */
className?: string;
}
/**
* CheckboxGroupItem props
*/
interface CheckboxGroupItemProps extends Omit {
/** Value for this checkbox item */
value: string;
}
/**
* Checkbox component for boolean selection
*
* @example
* ```tsx
*
*
*
*
* ```
*/
declare const Checkbox: react.ForwardRefExoticComponent>;
/**
* CheckboxGroup component for managing multiple checkboxes
*
* @example
* ```tsx
*
*
*
*
* ```
*/
declare const CheckboxGroup: react.ForwardRefExoticComponent>;
/**
* CheckboxGroupItem component for use within CheckboxGroup
*/
declare const CheckboxGroupItem: react.ForwardRefExoticComponent>;
/** Switch variant styles */
type SwitchVariant = 'solid' | 'soft' | 'outline';
/**
* Switch props
*/
interface SwitchProps extends Omit, 'onChange'> {
/** Size of the switch */
size?: SwitchSize;
/** Color theme */
color?: Color;
/** Visual variant */
variant?: SwitchVariant;
/** Whether the switch is checked */
checked?: boolean;
/** Default checked state (uncontrolled) */
defaultChecked?: boolean;
/** Callback when checked state changes */
onCheckedChange?: (checked: boolean) => void;
/** Whether the switch is disabled */
disabled?: boolean;
/** Whether the switch is required */
required?: boolean;
/** Whether the switch is in an invalid state */
invalid?: boolean;
/** Whether the switch is in a loading state */
loading?: boolean;
/** Name for form submission */
name?: string;
/** Value for form submission */
value?: string;
/** Label text */
label?: ReactNode;
/**
* Description text
* @deprecated Use Field wrapper with FieldDescription instead for better accessibility
*/
description?: ReactNode;
/** Position of the label relative to switch */
labelPosition?: 'start' | 'end';
/** Track labels for on/off states */
trackLabels?: {
on?: string;
off?: string;
};
/** Custom thumb icon */
thumbIcon?: ReactNode;
}
/**
* Switch component for toggling boolean values
*
* @example
* ```tsx
*
*
*
*
*
* ```
*/
declare const Switch: react.ForwardRefExoticComponent>;
/** Radio variant - uses core ColorVariant for consistency */
type RadioVariant = ColorVariant;
/**
* RadioGroup props
*/
interface RadioGroupProps extends Omit, 'onChange'> {
/** Size of the radio buttons */
size?: RadioSize;
/** Color theme */
color?: Color;
/** Visual variant */
variant?: RadioVariant;
/** Current value (controlled) */
value?: string;
/** Default value (uncontrolled) */
defaultValue?: string;
/** Callback when value changes */
onValueChange?: (value: string) => void;
/** Whether the group is disabled */
disabled?: boolean;
/** Whether a selection is required */
required?: boolean;
/** Whether the group is in an invalid state */
invalid?: boolean;
/** Name for form submission */
name?: string;
/** Orientation of the group */
orientation?: 'horizontal' | 'vertical';
/** Whether to loop keyboard navigation */
loop?: boolean;
/** Gap between items */
gap?: 'sm' | 'md' | 'lg';
/** Radio items */
children: ReactNode;
}
/**
* RadioGroupItem props
*/
interface RadioGroupItemProps extends Omit, 'value'> {
/** Value of this radio item */
value: string;
/** Whether this item is disabled */
disabled?: boolean;
/** Label text */
label?: ReactNode;
/** Description text */
description?: ReactNode;
/** Position of the label relative to radio */
labelPosition?: 'start' | 'end';
}
/**
* RadioCard props for card-style radio buttons
*/
interface RadioCardProps {
/** Value of this radio card */
value: string;
/** Whether this card is disabled */
disabled?: boolean;
/** Card title */
title?: ReactNode;
/** Card description */
description?: ReactNode;
/** Card icon */
icon?: ReactNode;
/** Accessible label for the radio card */
'aria-label'?: string;
/** ID of element that describes this radio card */
'aria-describedby'?: string;
/** Additional CSS classes */
className?: string;
}
/**
* RadioGroup component for single selection from multiple options
*
* @example
* ```tsx
*
*
*
*
* ```
*/
declare const RadioGroup: react.ForwardRefExoticComponent>;
/**
* RadioGroupItem component for individual radio options
*/
declare const RadioGroupItem: react.ForwardRefExoticComponent>;
/**
* RadioCard component for card-style radio buttons
*
* @example
* ```tsx
*
*
* } />
*
* ```
*/
declare const RadioCard: react.ForwardRefExoticComponent>;
/** Select visual variants */
type SelectVariant = 'outline' | 'filled' | 'flushed';
/**
* Select props
*/
interface SelectProps {
/** Accessible label for the select trigger */
'aria-label'?: string;
/** ID of element that labels the select */
'aria-labelledby'?: string;
/** ID of element that describes the select */
'aria-describedby'?: string;
/** ID for the select trigger */
id?: string;
/** Size of the select */
size?: Size;
/** Color theme */
color?: Color;
/** Visual variant */
variant?: SelectVariant;
/** Current value (controlled) */
value?: string;
/** Default value (uncontrolled) */
defaultValue?: string;
/** Callback when value changes */
onValueChange?: (value: string) => void;
/** Whether the select is open */
open?: boolean;
/** Default open state */
defaultOpen?: boolean;
/** Callback when open state changes */
onOpenChange?: (open: boolean) => void;
/** Whether the select is disabled */
disabled?: boolean;
/** Whether a selection is required */
required?: boolean;
/** Name for form submission */
name?: string;
/** Placeholder text */
placeholder?: string;
/** Whether the select has an error state */
invalid?: boolean;
/** Whether the select takes full width */
fullWidth?: boolean;
/** Whether the select is clearable */
clearable?: boolean;
/** Callback when clear button is clicked */
onClear?: () => void;
/** Select options */
children: ReactNode;
/** Additional class name for trigger */
className?: string;
}
/**
* SelectItem props
*/
interface SelectItemProps extends Omit, 'value'> {
/** Value of this option */
value: string;
/** Whether this option is disabled */
disabled?: boolean;
/** Text value for typeahead */
textValue?: string;
/** Icon to display before the item */
icon?: ReactNode;
/** Description text */
description?: string;
}
/**
* SelectGroup props
*/
interface SelectGroupProps extends ComponentPropsWithoutRef<'div'> {
/** Label for the group */
label?: string;
}
/**
* Select component for dropdown selection
*
* @example
* ```tsx
*
* ```
*/
declare const Select: react.ForwardRefExoticComponent>;
/**
* SelectItem component for individual select options
*/
declare const SelectItem: react.ForwardRefExoticComponent>;
/**
* SelectGroup component for grouping select options
*/
declare const SelectGroup: react.ForwardRefExoticComponent>;
/**
* SelectSeparator component for visual separation
*/
declare const SelectSeparator: react.ForwardRefExoticComponent, HTMLDivElement>, "ref"> & react.RefAttributes>;
/** Slider variant styles */
type SliderVariant = 'solid' | 'soft';
/** Slider mark definition */
interface SliderMark {
value: number;
label?: ReactNode;
}
interface SliderProps extends Omit, 'defaultValue' | 'onChange' | 'dir'> {
/** Size of the slider */
size?: SliderSize;
/** Color theme */
color?: Color;
/** Visual variant */
variant?: SliderVariant;
/** Current value (controlled) */
value?: number[];
/** Default value (uncontrolled) */
defaultValue?: number[];
/** Callback when value changes */
onValueChange?: (value: number[]) => void;
/** Callback when value is committed (on mouse up) */
onValueCommit?: (value: number[]) => void;
/** Minimum value */
min?: number;
/** Maximum value */
max?: number;
/** Step increment */
step?: number;
/** Minimum steps between thumbs for range sliders */
minStepsBetweenThumbs?: number;
/** Whether the slider is disabled */
disabled?: boolean;
/** Whether the slider is in an invalid state */
invalid?: boolean;
/** Orientation of the slider */
orientation?: 'horizontal' | 'vertical';
/** Whether the slider is inverted */
inverted?: boolean;
/** Name for form submission */
name?: string;
/** Show value label above thumb */
showValue?: boolean;
/** Format function for value display */
formatValue?: (value: number) => string;
/** Label for the slider */
label?: ReactNode;
/** Helper text below slider */
helperText?: ReactNode;
/** Show tooltip on hover/drag */
showTooltip?: boolean;
/** Marks to display on the slider track */
marks?: SliderMark[] | boolean;
/** Whether marks should be included as steps */
markSteps?: boolean;
/** Additional CSS classes */
className?: string;
}
/**
* Slider component for selecting numeric values
*
* @example
* ```tsx
*
*
*
* ```
*/
declare const Slider: react.ForwardRefExoticComponent>;
interface FileUploadProps {
/** Size of the file upload component */
size?: Size;
/** Accepted file types (e.g., "image/*", ".pdf") */
accept?: string;
/** Allow multiple file selection */
multiple?: boolean;
/** Maximum file size in bytes */
maxFileSize?: number;
/** Maximum number of files */
maxFiles?: number;
/** Whether the upload is disabled */
disabled?: boolean;
/** Whether the field is required */
required?: boolean;
/** Whether the upload is in an invalid state */
invalid?: boolean;
/** Callback when files are selected */
onFilesChange?: (files: File[]) => void;
/** Callback when files are rejected */
onFilesRejected?: (files: FileRejection[]) => void;
/** Custom content for dropzone */
children?: ReactNode;
/** Additional CSS classes */
className?: string;
/** Name for form submission */
name?: string;
/** Label for the upload area */
label?: string;
/** Helper text */
helperText?: string;
/** Show file list */
showFileList?: boolean;
/** Allow drag and drop */
allowDrag?: boolean;
}
interface FileRejection {
file: File;
reason: 'size' | 'type' | 'count';
message: string;
}
interface FileUploadItemProps {
file: File;
onRemove?: () => void;
showSize?: boolean;
showPreview?: boolean;
}
/**
* FileUploadItem component for displaying uploaded files
*/
declare function FileUploadItem({ file, onRemove, showSize, showPreview }: FileUploadItemProps): react_jsx_runtime.JSX.Element;
/**
* FileUpload component for uploading files with drag & drop support
*
* @example
* ```tsx
* console.log(files)}
* />
* ```
*/
declare const FileUpload: react.ForwardRefExoticComponent>;
interface FormGroupProps extends Omit, 'children' | 'dir'> {
/** Legend/title for the group */
legend?: string;
/** Description for the group */
description?: string;
/** Whether the group is disabled */
disabled?: boolean;
/** Whether the group is required */
required?: boolean;
/** Children components */
children: ReactNode;
/** Additional CSS classes */
className?: string;
/** Spacing between items */
spacing?: 'sm' | 'md' | 'lg';
/** Layout direction */
direction?: 'vertical' | 'horizontal';
/** ID for the fieldset */
id?: string;
}
/**
* FormGroup component for grouping related form fields
*
* @example
* ```tsx
*
*
*
*
* ```
*/
declare const FormGroup: react.ForwardRefExoticComponent>;
interface FieldProps extends Omit, 'children'> {
/** Label text */
label?: string;
/** Helper text displayed below the input */
helperText?: string;
/** Error text displayed when invalid */
errorText?: string;
/** Whether the field is required */
required?: boolean;
/** Whether the field is invalid */
invalid?: boolean;
/** Whether the field is disabled */
disabled?: boolean;
/** Size of the field elements */
size?: Size;
/** Optional text displayed on the right side of the label */
optionalText?: string;
/** Children components (usually an input) */
children: ReactNode;
/** Additional CSS classes */
className?: string;
/** ID for the field (used to link label with input) */
id?: string;
}
/**
* Field component that wraps an input with label, helper text, and error text
*
* @example
* ```tsx
*
*
*
*
*
*
*
* ```
*/
declare const Field: react.ForwardRefExoticComponent>;
/**
* InputGroup props
*/
interface InputGroupProps extends Omit, 'children'> {
/** Size of the input group - passed to child elements */
size?: Size;
/** Element to display at the start of the input (inside border) */
startElement?: ReactNode;
/** Element to display at the end of the input (inside border) */
endElement?: ReactNode;
/**
* Override pointer-events behaviour for the start slot.
*
* - `undefined` (default): smart — wrapper is inert, but interactive
* descendants (`button`, `a`, `input`, `[role="button"]`) receive clicks.
* - `'auto'`: the entire slot receives pointer events.
* - `'none'`: the entire slot (including interactive descendants) is inert.
*/
startElementPointerEvents?: 'none' | 'auto';
/** See {@link InputGroupProps.startElementPointerEvents}. */
endElementPointerEvents?: 'none' | 'auto';
/** Children (typically Input component) */
children: ReactNode;
}
/**
* InputAddon props
*/
interface InputAddonProps extends Omit, 'children'> {
/** Size of the addon */
size?: Size;
/** Placement of the addon */
placement?: 'start' | 'end';
/** Addon content */
children: ReactNode;
}
/**
* InputAddon component for adding addons to inputs (outside the input border)
*
* @example
* ```tsx
*