0
# Core System and Theme
1

2
NextUI's core system provides the foundational infrastructure for theming, provider configuration, and styling utilities that power all components in the library.
3

4
## Capabilities
5

6
### NextUI Provider
7

8
The root provider component that wraps your application and provides global configuration for themes, localization, animations, and routing.
9

10
```typescript { .api }
11
interface NextUIProviderProps {
12
  /** Application content */
13
  children: React.ReactNode;
14
  /** Locale for internationalization (e.g., "en-US", "fr-FR") */
15
  locale?: string;
16
  /** Default theme to apply ("light" or "dark") */
17
  theme?: DefaultThemeType;
18
  /** Custom theme configurations */
19
  themes?: ConfigThemes;
20
  /** Default theme key when using custom themes */
21
  defaultTheme?: string;
22
  /** Disable all animations globally */
23
  disableAnimation?: boolean;
24
  /** Disable ripple effects globally */
25
  disableRipple?: boolean;
26
  /** Skip Framer Motion animations for better performance */
27
  skipFramerMotionAnimations?: boolean;
28
  /** Form validation behavior */
29
  validationBehavior?: "aria" | "native";
30
  /** Router navigation function for client-side routing */
31
  navigate?: (path: string) => void;
32
  /** Whether to create a portal container */
33
  createPortalContainer?: boolean;
34
  /** Calendar systems to support */
35
  calendars?: SupportedCalendars[];
36
}
37

38
function NextUIProvider(props: NextUIProviderProps): JSX.Element;
39

40
type DefaultThemeType = "light" | "dark";
41

42
type SupportedCalendars = 
43
  | "buddhist" | "ethiopic" | "ethioaa" | "coptic" 
44
  | "hebrew" | "indian" | "islamic-civil" | "islamic-tbla" 
45
  | "islamic-umalqura" | "japanese" | "persian" | "roc" | "gregory";
46
```
47

48
**Usage Examples:**
49

50
```typescript
51
import React from "react";
52
import { NextUIProvider } from "@nextui-org/react";
53
import { useNavigate } from "react-router-dom";
54

55
function App() {
56
  const navigate = useNavigate();
57

58
  return (
59
    <NextUIProvider navigate={navigate} theme="light" locale="en-US">
60
      {/* Your app content */}
61
    </NextUIProvider>
62
  );
63
}
64
```
65

66
For CommonJS:
67

68
```javascript
69
const React = require("react");
70
const { NextUIProvider } = require("@nextui-org/react");
71

72
function App() {
73
  return (
74
    <NextUIProvider theme="light" locale="en-US">
75
      {/* Your app content */}
76
    </NextUIProvider>
77
  );
78
}
79
```
80

81
### Provider Context
82

83
Access NextUI provider state and configuration throughout your component tree.
84

85
```typescript { .api }
86
interface ProviderContextProps {
87
  theme?: DefaultThemeType;
88
  themes?: ConfigThemes;
89
  defaultTheme?: string;
90
  disableAnimation?: boolean;
91
  disableRipple?: boolean;
92
  validationBehavior?: "aria" | "native";
93
  locale?: string;
94
  navigate?: (path: string) => void;
95
  createPortalContainer?: boolean;
96
}
97

98
const ProviderContext: React.Context<ProviderContextProps>;
99

100
/**
101
 * Hook to access NextUI provider context
102
 * @returns Provider context props or undefined if outside provider
103
 */
104
function useProviderContext(): ProviderContextProps | undefined;
105
```
106

107
### Theme Configuration
108

109
Advanced theme configuration system supporting multiple themes, custom colors, and responsive design tokens.
110

111
```typescript { .api }
112
interface BaseThemeUnit {
113
  small?: string;
114
  medium?: string;
115
  large?: string;
116
}
117

118
interface FontThemeUnit extends BaseThemeUnit {
119
  tiny?: string;
120
}
121

122
interface LayoutTheme {
123
  /** Spacing scale values */
124
  spacingUnit?: number;
125
  /** Disable default theme styles */
126
  disableAnimation?: boolean;
127
  /** Disable ripple effects */
128
  disableRipple?: boolean;
129
  /** Hover opacity for interactive elements */
130
  hoverOpacity?: number;
131
  /** Active opacity for pressed elements */
132
  activeOpacity?: number;
133
  /** Disabled opacity for disabled elements */
134
  disabledOpacity?: number;
135
  /** Divider weight/thickness */
136
  dividerWeight?: string;
137
  /** Font size configuration */
138
  fontSize?: FontThemeUnit;
139
  /** Line height configuration */
140
  lineHeight?: FontThemeUnit;
141
  /** Border radius configuration */
142
  radius?: BaseThemeUnit;
143
  /** Border width configuration */
144
  borderWidth?: BaseThemeUnit;
145
  /** Box shadow configuration */
146
  boxShadow?: BaseThemeUnit;
147
}
148

149
interface ConfigTheme extends LayoutTheme {
150
  /** Color palette for the theme */
151
  colors?: Record<string, any>;
152
}
153

154
interface ConfigThemes {
155
  /** Light theme configuration */
156
  light?: ConfigTheme;
157
  /** Dark theme configuration */
158
  dark?: ConfigTheme;
159
  /** Custom theme configurations */
160
  [key: string]: ConfigTheme | undefined;
161
}
162

163
interface NextUIPluginConfig {
164
  /** Theme configuration */
165
  themes?: ConfigThemes;
166
  /** Default theme */
167
  defaultTheme?: DefaultThemeType;
168
  /** Layout configuration */
169
  layout?: LayoutTheme;
170
  /** Default extend theme */
171
  defaultExtendTheme?: DefaultThemeType;
172
  /** Additional CSS variables prefix */
173
  prefix?: string;
174
  /** Add common colors to palette */
175
  addCommonColors?: boolean;
176
}
177
```
178

179
### Styling Utilities
180

181
Core styling utilities built on Tailwind Variants for consistent component styling.
182

183
```typescript { .api }
184
/**
185
 * Tailwind Variants function for creating component variants
186
 */
187
function tv<S extends Record<string, any>>(
188
  config: TVConfig<S>
189
): (...args: any[]) => string;
190

191
interface TVConfig<S = {}> {
192
  /** Base classes applied to all variants */
193
  base?: string | string[];
194
  /** Variant configurations */
195
  variants?: Record<string, Record<string, string | string[]>>;
196
  /** Slot-based styling for complex components */
197
  slots?: S;
198
  /** Default variant selections */
199
  defaultVariants?: Record<string, any>;
200
  /** Compound variants for multiple variant combinations */
201
  compoundVariants?: Array<{
202
    /** Variant conditions */
203
    [key: string]: any;
204
    /** Classes to apply when conditions match */
205
    class?: string | string[];
206
    /** Slot classes to apply when conditions match */
207
    [K in keyof S]?: string | string[];
208
  }>;
209
  /** Responsive variants */
210
  responsiveVariants?: string[] | ResponsiveVariantsConfig;
211
}
212

213
type VariantProps<T> = T extends (...args: any[]) => any
214
  ? Parameters<T>[0]
215
  : never;
216

217
type TV = typeof tv;
218

219
/**
220
 * Class name utility function (alias for clsx/cn)
221
 */
222
function cn(...inputs: ClassValue[]): string;
223

224
type ClassValue = 
225
  | string
226
  | number
227
  | boolean
228
  | undefined
229
  | null
230
  | ClassValue[]
231
  | Record<string, any>;
232

233
/**
234
 * Merge classes utility
235
 */
236
function mergeClasses(...classes: string[]): string;
237
```
238

239
### Base CSS Classes
240

241
Pre-defined CSS class utilities for common styling patterns.
242

243
```typescript { .api }
244
/** Base component styles */
245
const baseStyles: (props?: any) => string;
246

247
/** Focus ring styles */
248
const ringClasses: string[];
249
const focusVisibleClasses: string[];
250
const dataFocusVisibleClasses: string[];
251
const groupDataFocusVisibleClasses: string[];
252

253
/** Layout utilities */
254
const translateCenterClasses: string[];
255
const absoluteFullClasses: string[];
256

257
/** Border collapse utility for adjacent elements */
258
const collapseAdjacentVariantBorders: (...args: any[]) => string;
259

260
/** Hidden input styling for form controls */
261
const hiddenInputClasses: string[];
262

263
/** Color variant utilities */
264
const colorVariants: string[];
265

266
/** Common design tokens */
267
const COMMON_UNITS: {
268
  sm: string;
269
  md: string;
270
  lg: string;
271
  xl: string;
272
};
273

274
/** Tailwind merge configuration */
275
const twMergeConfig: Record<string, any>;
276
```
277

278
### Slot-Based Styling
279

280
Type utilities for component slot-based styling systems.
281

282
```typescript { .api }
283
/**
284
 * Utility type for mapping component slots to CSS classes
285
 */
286
type SlotsToClasses<S extends string> = {
287
  [K in S]?: string;
288
};
289

290
/**
291
 * Extract slot keys from component variants
292
 */
293
type SlotProps<T> = T extends Record<infer S, any> ? S : never;
294
```
295

296
### System Types
297

298
Core TypeScript utilities for component system integration.
299

300
```typescript { .api }
301
/**
302
 * Polymorphic component type for 'as' prop support
303
 */
304
type As<Props = any> = React.ElementType<Props>;
305

306
/**
307
 * DOM element type utilities
308
 */
309
type DOMElement = Element;
310
type DOMElements = keyof JSX.IntrinsicElements;
311
type CapitalizedDOMElements = Capitalize<DOMElements>;
312

313
/**
314
 * DOM attributes utility
315
 */
316
type DOMAttributes<T = Element> = React.DOMAttributes<T>;
317

318
/**
319
 * Component prop utilities
320
 */
321
type OmitCommonProps<T, K extends keyof any = never> = Omit<T, "id" | "children" | K>;
322

323
type RightJoinProps<
324
  SourceProps extends object = {},
325
  OverrideProps extends object = {}
326
> = OmitCommonProps<SourceProps, keyof OverrideProps> & OverrideProps;
327

328
type MergeWithAs<
329
  ComponentProps extends object,
330
  AsProps extends object,
331
  AdditionalProps extends object = {},
332
  AsComponent extends As = As
333
> = RightJoinProps<ComponentProps, AdditionalProps> & 
334
    RightJoinProps<AsProps, AdditionalProps> & {
335
      as?: AsComponent;
336
    };
337

338
type PropsOf<T extends As> = React.ComponentPropsWithoutRef<T> & {
339
  as?: T;
340
};
341

342
/**
343
 * Prop getter function type
344
 */
345
type PropGetter<P = Record<string, unknown>, R = Record<string, unknown>> = (
346
  props?: P,
347
  forwardedRef?: React.Ref<any>
348
) => R;
349

350
/**
351
 * Enhanced forwardRef function
352
 */
353
type InternalForwardRefRenderFunction<T, P = {}> = (
354
  props: P,
355
  ref: React.ForwardedRef<T>
356
) => React.ReactElement | null;
357

358
function forwardRef<T, P = {}>(
359
  render: InternalForwardRefRenderFunction<T, P>
360
): React.ForwardRefExoticComponent<React.PropsWithoutRef<P> & React.RefAttributes<T>>;
361
```
362

363
### Variant Extension System
364

365
Utilities for extending and customizing component variants.
366

367
```typescript { .api }
368
/**
369
 * Extend component variants with custom styling
370
 */
371
function extendVariants<T extends (...args: any[]) => any>(
372
  component: T,
373
  variants: ExtendVariantProps<T>,
374
  defaultVariants?: Record<string, any>
375
): T;
376

377
type ExtendVariantProps<T> = T extends TV
378
  ? {
379
      variants?: Record<string, Record<string, any>>;
380
      defaultVariants?: Record<string, any>;
381
      compoundVariants?: Array<Record<string, any>>;
382
    }
383
  : never;
384

385
type ExtendVariantWithSlotsProps<T> = T extends Record<string, any>
386
  ? {
387
      base?: Record<keyof T, any>;
388
      variants?: Record<string, Record<string, Record<keyof T, any>>>;
389
      defaultVariants?: Record<string, any>;
390
      compoundVariants?: Array<Record<string, any>>;
391
    }
392
  : never;
393

394
type ExtendVariants<T> = T extends Record<string, any>
395
  ? ExtendVariantWithSlotsProps<T>
396
  : ExtendVariantProps<T>;
397

398
/**
399
 * Prop mapping utilities for variants
400
 */
401
function mapPropsVariants<T, K>(
402
  props: T,
403
  variantKeys: K[],
404
  removeVariantProps?: boolean
405
): [T, Record<string, any>];
406

407
function mapPropsVariantsWithCommon<T, K, C>(
408
  props: T,
409
  variantKeys: K[],
410
  commonKeys: C[],
411
  removeVariantProps?: boolean
412
): [T, Record<string, any>, Record<string, any>];
413
```
414

415
### Selection System
416

417
Shared selection state management for interactive components.
418

419
```typescript { .api }
420
/**
421
 * Selection state interface for components with selectable items
422
 */
423
interface SharedSelection {
424
  /** Currently selected keys */
425
  selectedKeys?: Selection;
426
  /** Default selected keys for uncontrolled mode */
427
  defaultSelectedKeys?: Selection;
428
  /** Selection mode */
429
  selectionMode?: SelectionMode;
430
  /** Selection behavior on interaction */
431
  selectionBehavior?: SelectionBehavior;
432
  /** Whether to prevent empty selection */
433
  disallowEmptySelection?: boolean;
434
  /** Selection change callback */
435
  onSelectionChange?: (keys: Selection) => void;
436
}
437

438
type Selection = "all" | Set<React.Key>;
439
type SelectionMode = "none" | "single" | "multiple";
440
type SelectionBehavior = "toggle" | "replace";
441
```
442

443
### Utility Functions
444

445
```typescript { .api }
446
/**
447
 * Convert value to iterator
448
 */
449
function toIterator<T>(value: Iterable<T> | (() => Iterable<T>)): Iterator<T>;
450

451
/**
452
 * Check if element is NextUI component
453
 */
454
function isNextUIEl(element: React.ReactElement): boolean;
455
```
456

457
**Usage Examples:**
458

459
```typescript
460
// Custom theme configuration
461
import { NextUIProvider } from "@nextui-org/react";
462

463
const customThemes = {
464
  light: {
465
    colors: {
466
      primary: {
467
        50: "#f0f9ff",
468
        500: "#3b82f6",
469
        900: "#1e3a8a",
470
        DEFAULT: "#3b82f6",
471
        foreground: "#ffffff",
472
      },
473
    },
474
  },
475
  dark: {
476
    colors: {
477
      primary: {
478
        50: "#1e3a8a", 
479
        500: "#3b82f6",
480
        900: "#f0f9ff",
481
        DEFAULT: "#3b82f6",
482
        foreground: "#000000",
483
      },
484
    },
485
  },
486
};
487

488
function App() {
489
  return (
490
    <NextUIProvider themes={customThemes} defaultTheme="light">
491
      {/* App content */}
492
    </NextUIProvider>
493
  );
494
}
495

496
// Using Tailwind Variants
497
import { tv } from "@nextui-org/react";
498

499
const button = tv({
500
  base: "font-medium bg-blue-500 text-white hover:opacity-80 pressed:scale-95",
501
  variants: {
502
    color: {
503
      primary: "bg-blue-500",
504
      secondary: "bg-gray-500", 
505
      danger: "bg-red-500",
506
    },
507
    size: {
508
      sm: "text-sm px-2 py-1",
509
      md: "text-base px-4 py-2",
510
      lg: "text-lg px-6 py-3",
511
    },
512
    disabled: {
513
      true: "opacity-50 pointer-events-none",
514
    },
515
  },
516
  defaultVariants: {
517
    size: "md",
518
    color: "primary",
519
  },
520
});
521

522
// Extending component variants
523
import { Button, extendVariants } from "@nextui-org/react";
524

525
const MyButton = extendVariants(Button, {
526
  variants: {
527
    color: {
528
      olive: "text-[#000] bg-[#84cc16]",
529
      orange: "bg-[#ff8c00] text-[#fff]",
530
      violet: "bg-[#8b5cf6] text-[#fff]",
531
    },
532
    isDisabled: {
533
      true: "bg-[#eaeaea] text-[#000] opacity-50 cursor-not-allowed",
534
    },
535
  },
536
  defaultVariants: {
537
    color: "olive",
538
    size: "md",
539
  },
540
});
541
```