0
# Theme System
1

2
Theme configuration, color modes, design tokens, and responsive design utilities for comprehensive styling control.
3

4
## Capabilities
5

6
### NativeBaseProvider
7

8
Main provider component that wraps your application and provides theme context.
9

10
```typescript { .api }
11
/**
12
 * Main provider component that wraps the app with NativeBase theme context
13
 * @param props - NativeBase configuration props
14
 * @returns JSX element providing theme context to children
15
 */
16
function NativeBaseProvider(props: INativebaseConfig): JSX.Element;
17

18
interface INativebaseConfig {
19
  theme?: ICustomTheme;
20
  initialColorMode?: ColorMode;
21
  colorModeManager?: StorageManager;
22
  config?: {
23
    dependencies?: {
24
      'linear-gradient'?: any;
25
    };
26
    suppressColorAccessibilityWarning?: boolean;
27
  };
28
  children?: React.ReactNode;
29
}
30
```
31

32
**Usage Example:**
33

34
```typescript
35
import React from 'react';
36
import { NativeBaseProvider, extendTheme } from 'native-base';
37

38
const theme = extendTheme({
39
  colors: {
40
    primary: {
41
      50: '#e3f2f9',
42
      500: '#0ea5e9',
43
      900: '#0c4a6e',
44
    },
45
  },
46
});
47

48
function App() {
49
  return (
50
    <NativeBaseProvider theme={theme}>
51
      {/* Your app components */}
52
    </NativeBaseProvider>
53
  );
54
}
55
```
56

57
### Theme Extension
58

59
Function for extending and customizing the default theme.
60

61
```typescript { .api }
62
/**
63
 * Extends the default theme with custom configuration
64
 * @param theme - Partial theme object with custom values
65
 * @returns Complete theme object with custom overrides
66
 */
67
function extendTheme(theme: Partial<ITheme>): ITheme;
68

69
interface ITheme {
70
  colors: Colors;
71
  space: Space;
72
  sizes: Sizes;
73
  fonts: Fonts;
74
  fontSizes: FontSizes;
75
  fontWeights: FontWeights;
76
  lineHeights: LineHeights;
77
  letterSpacings: LetterSpacings;
78
  radii: Radii;
79
  shadows: Shadows;
80
  borders: Borders;
81
  breakpoints: Breakpoints;
82
  components: ComponentThemes;
83
  config: ThemeConfig;
84
}
85

86
interface ICustomTheme extends Partial<ITheme> {}
87

88
type Colors = {
89
  [key: string]: string | { [key: string]: string };
90
};
91

92
type Space = string[] | { [key: string]: string };
93
type Sizes = { [key: string]: string };
94
type Fonts = { [key: string]: string };
95
type FontSizes = { [key: string]: string };
96
type FontWeights = { [key: string]: string | number };
97
type LineHeights = { [key: string]: string | number };
98
type LetterSpacings = { [key: string]: string };
99
type Radii = { [key: string]: string };
100
type Shadows = { [key: string]: string };
101
type Borders = { [key: string]: string };
102
type Breakpoints = { [key: string]: string };
103

104
interface ComponentThemes {
105
  [componentName: string]: ComponentTheme;
106
}
107

108
interface ComponentTheme {
109
  baseStyle?: StyleObject;
110
  sizes?: { [size: string]: StyleObject };
111
  variants?: { [variant: string]: StyleObject };
112
  defaultProps?: { [prop: string]: any };
113
}
114
```
115

116
### Color Mode Management
117

118
Hooks and utilities for managing light/dark theme modes.
119

120
```typescript { .api }
121
/**
122
 * Hook for managing color mode state
123
 * @returns Color mode utilities and current mode
124
 */
125
function useColorMode(): ColorModeReturn;
126

127
/**
128
 * Hook for selecting values based on current color mode
129
 * @param light - Value to use in light mode
130
 * @param dark - Value to use in dark mode
131
 * @returns Value based on current color mode
132
 */
133
function useColorModeValue<T>(light: T, dark: T): T;
134

135
/**
136
 * Hook for accessible color handling
137
 * @returns Accessible color utilities
138
 */
139
function useAccessibleColors(): AccessibleColorsReturn;
140

141
interface ColorModeReturn {
142
  colorMode: ColorMode;
143
  toggleColorMode: () => void;
144
  setColorMode: (mode: ColorMode) => void;
145
}
146

147
type ColorMode = "light" | "dark";
148

149
interface AccessibleColorsReturn {
150
  accessibleColors: Colors;
151
  contrastColors: Colors;
152
}
153

154
interface StorageManager {
155
  get: (key: string) => Promise<string | null>;
156
  set: (key: string, value: string) => Promise<void>;
157
}
158
```
159

160
**Usage Examples:**
161

162
```typescript
163
import { useColorMode, useColorModeValue, Button } from 'native-base';
164

165
function ThemeToggle() {
166
  const { colorMode, toggleColorMode } = useColorMode();
167
  
168
  return (
169
    <Button onPress={toggleColorMode}>
170
      Switch to {colorMode === 'light' ? 'dark' : 'light'} mode
171
    </Button>
172
  );
173
}
174

175
function ThemedComponent() {
176
  const bg = useColorModeValue('white', 'gray.800');
177
  const text = useColorModeValue('gray.800', 'white');
178
  
179
  return (
180
    <Box bg={bg}>
181
      <Text color={text}>This text adapts to the theme</Text>
182
    </Box>
183
  );
184
}
185
```
186

187
### Theme Access Hooks
188

189
Hooks for accessing theme values and tokens.
190

191
```typescript { .api }
192
/**
193
 * Hook for accessing the complete theme object
194
 * @returns Complete theme configuration object
195
 */
196
function useTheme(): ITheme;
197

198
/**
199
 * Hook for accessing specific theme tokens
200
 * @param token - Theme token path (e.g., "colors.primary.500")
201
 * @param fallback - Fallback value if token not found
202
 * @returns Token value or fallback
203
 */
204
function useToken(token: string, fallback?: any): any;
205

206
/**
207
 * Hook for resolving theme props with component theme integration
208
 * @param props - Component props to resolve
209
 * @param componentTheme - Component-specific theme configuration
210
 * @returns Resolved props with theme values
211
 */
212
function useThemeProps(props: any, componentTheme?: ComponentTheme): any;
213

214
/**
215
 * Hook for resolving props with component theme integration
216
 * @param component - Component name for theme lookup
217
 * @param props - Component props to resolve
218
 * @returns Props enhanced with component theme
219
 */
220
function usePropsWithComponentTheme(component: string, props: any): any;
221
```
222

223
**Usage Examples:**
224

225
```typescript
226
import { useTheme, useToken } from 'native-base';
227

228
function CustomComponent() {
229
  const theme = useTheme();
230
  const primaryColor = useToken('colors.primary.500', '#0ea5e9');
231
  
232
  return (
233
    <Box bg={primaryColor}>
234
      <Text>Using theme token: {primaryColor}</Text>
235
    </Box>
236
  );
237
}
238
```
239

240
### Responsive Design
241

242
Utilities for responsive design and breakpoint management.
243

244
```typescript { .api }
245
/**
246
 * Hook for selecting values based on current breakpoint
247
 * @param values - Responsive value object or array
248
 * @returns Value for current breakpoint
249
 */
250
function useBreakpointValue<T>(values: ResponsiveValue<T>): T;
251

252
/**
253
 * Hook for resolving responsive props based on breakpoints
254
 * @param props - Props object with potentially responsive values
255
 * @returns Props resolved for current breakpoint
256
 */
257
function useBreakpointResolvedProps(props: any): any;
258

259
/**
260
 * Hook for media query matching
261
 * @param query - Media query string or breakpoint
262
 * @returns Array of boolean values for query matches
263
 */
264
function useMediaQuery(query: string | string[]): boolean[];
265

266
type ResponsiveValue<T> = 
267
  | T 
268
  | T[] 
269
  | { 
270
      base?: T; 
271
      sm?: T; 
272
      md?: T; 
273
      lg?: T; 
274
      xl?: T; 
275
      '2xl'?: T; 
276
    };
277
```
278

279
**Usage Examples:**
280

281
```typescript
282
import { useBreakpointValue, useMediaQuery, Box } from 'native-base';
283

284
function ResponsiveComponent() {
285
  const fontSize = useBreakpointValue({
286
    base: 'sm',
287
    sm: 'md', 
288
    md: 'lg',
289
    lg: 'xl'
290
  });
291
  
292
  const [isLargeScreen] = useMediaQuery('(min-width: 768px)');
293
  
294
  return (
295
    <Box>
296
      <Text fontSize={fontSize}>Responsive text</Text>
297
      {isLargeScreen && <Text>Only shown on large screens</Text>}
298
    </Box>
299
  );
300
}
301
```
302

303
### Platform-Specific Styling
304

305
Utilities for platform-specific styling and props.
306

307
```typescript { .api }
308
/**
309
 * Hook for applying platform-specific props
310
 * @param props - Props object with platform overrides
311
 * @returns Props resolved for current platform
312
 */
313
function usePlatformProps(props: any): any;
314
```
315

316
### Styled System Props
317

318
Core styled system properties available to all components.
319

320
```typescript { .api }
321
interface StyledProps {
322
  // Color props
323
  bg?: ResponsiveValue<string>;
324
  backgroundColor?: ResponsiveValue<string>;
325
  color?: ResponsiveValue<string>;
326
  opacity?: ResponsiveValue<number>;
327
  
328
  // Spacing props
329
  m?: ResponsiveValue<string | number>;
330
  margin?: ResponsiveValue<string | number>;
331
  mt?: ResponsiveValue<string | number>;
332
  mr?: ResponsiveValue<string | number>;
333
  mb?: ResponsiveValue<string | number>;
334
  ml?: ResponsiveValue<string | number>;
335
  mx?: ResponsiveValue<string | number>;
336
  my?: ResponsiveValue<string | number>;
337
  p?: ResponsiveValue<string | number>;
338
  padding?: ResponsiveValue<string | number>;
339
  pt?: ResponsiveValue<string | number>;
340
  pr?: ResponsiveValue<string | number>;
341
  pb?: ResponsiveValue<string | number>;
342
  pl?: ResponsiveValue<string | number>;
343
  px?: ResponsiveValue<string | number>;
344
  py?: ResponsiveValue<string | number>;
345
  
346
  // Layout props
347
  w?: ResponsiveValue<string | number>;
348
  width?: ResponsiveValue<string | number>;
349
  h?: ResponsiveValue<string | number>;
350
  height?: ResponsiveValue<string | number>;
351
  minW?: ResponsiveValue<string | number>;
352
  minWidth?: ResponsiveValue<string | number>;
353
  maxW?: ResponsiveValue<string | number>;
354
  maxWidth?: ResponsiveValue<string | number>;
355
  minH?: ResponsiveValue<string | number>;
356
  minHeight?: ResponsiveValue<string | number>;
357
  maxH?: ResponsiveValue<string | number>;
358
  maxHeight?: ResponsiveValue<string | number>;
359
  d?: ResponsiveValue<string>;
360
  display?: ResponsiveValue<string>;
361
  
362
  // Position props
363
  position?: ResponsiveValue<"absolute" | "relative" | "static">;
364
  top?: ResponsiveValue<string | number>;
365
  right?: ResponsiveValue<string | number>;
366
  bottom?: ResponsiveValue<string | number>;
367
  left?: ResponsiveValue<string | number>;
368
  zIndex?: ResponsiveValue<number>;
369
  
370
  // Flexbox props
371
  alignItems?: ResponsiveValue<"flex-start" | "flex-end" | "center" | "stretch" | "baseline">;
372
  alignContent?: ResponsiveValue<string>;
373
  justifyContent?: ResponsiveValue<"flex-start" | "flex-end" | "center" | "space-between" | "space-around" | "space-evenly">;
374
  flexWrap?: ResponsiveValue<"wrap" | "nowrap" | "wrap-reverse">;
375
  flexDirection?: ResponsiveValue<"row" | "column" | "row-reverse" | "column-reverse">;
376
  flex?: ResponsiveValue<number>;
377
  flexGrow?: ResponsiveValue<number>;
378
  flexShrink?: ResponsiveValue<number>;
379
  flexBasis?: ResponsiveValue<string | number>;
380
  alignSelf?: ResponsiveValue<string>;
381
  
382
  // Border props
383
  border?: ResponsiveValue<string>;
384
  borderWidth?: ResponsiveValue<string | number>;
385
  borderStyle?: ResponsiveValue<string>;
386
  borderColor?: ResponsiveValue<string>;
387
  borderRadius?: ResponsiveValue<string | number>;
388
  borderTop?: ResponsiveValue<string>;
389
  borderRight?: ResponsiveValue<string>;
390
  borderBottom?: ResponsiveValue<string>;
391
  borderLeft?: ResponsiveValue<string>;
392
  borderTopWidth?: ResponsiveValue<string | number>;
393
  borderRightWidth?: ResponsiveValue<string | number>;
394
  borderBottomWidth?: ResponsiveValue<string | number>;
395
  borderLeftWidth?: ResponsiveValue<string | number>;
396
  borderTopColor?: ResponsiveValue<string>;
397
  borderRightColor?: ResponsiveValue<string>;
398
  borderBottomColor?: ResponsiveValue<string>;
399
  borderLeftColor?: ResponsiveValue<string>;
400
  borderTopRadius?: ResponsiveValue<string | number>;
401
  borderRightRadius?: ResponsiveValue<string | number>;
402
  borderBottomRadius?: ResponsiveValue<string | number>;
403
  borderLeftRadius?: ResponsiveValue<string | number>;
404
  
405
  // Shadow props
406
  shadow?: ResponsiveValue<string | number>;
407
  shadowColor?: ResponsiveValue<string>;
408
  shadowOffset?: ResponsiveValue<{ width: number; height: number }>;
409
  shadowOpacity?: ResponsiveValue<number>;
410
  shadowRadius?: ResponsiveValue<number>;
411
  elevation?: ResponsiveValue<number>;
412
  
413
  // Typography props (for components that support text)
414
  fontFamily?: ResponsiveValue<string>;
415
  fontSize?: ResponsiveValue<string | number>;
416
  fontWeight?: ResponsiveValue<string | number>;
417
  lineHeight?: ResponsiveValue<string | number>;
418
  letterSpacing?: ResponsiveValue<string | number>;
419
  textAlign?: ResponsiveValue<"left" | "right" | "center" | "justify">;
420
  textTransform?: ResponsiveValue<"none" | "capitalize" | "uppercase" | "lowercase">;
421
  textDecoration?: ResponsiveValue<string>;
422
}
423
```
424

425
### Theme Tools
426

427
Utility functions for theme manipulation and color calculations.
428

429
```typescript { .api }
430
/**
431
 * Utility tools for theme manipulation
432
 */
433
const themeTools: {
434
  getColor: (theme: ITheme, color: string, fallback?: string) => string;
435
  mode: (light: any, dark: any) => (props: any) => any;
436
  transparentize: (color: string, opacity: number) => string;
437
  rgba: (color: string, alpha: number) => string;
438
};
439

440
/**
441
 * Extract color value from theme
442
 * @param theme - Theme object
443
 * @param color - Color token path
444
 * @param fallback - Fallback color value
445
 * @returns Resolved color value
446
 */
447
function getColor(theme: ITheme, color: string, fallback?: string): string;
448
```
449

450
### Legacy Theme Support
451

452
Support for v3.3.x theme compatibility.
453

454
```typescript { .api }
455
/**
456
 * V3.3.x compatible theme object
457
 */
458
const v33xTheme: V33xTheme;
459

460
/**
461
 * V3 compatible theme configuration
462
 */
463
const v3CompatibleTheme: ITheme;
464

465
interface V33xTheme {
466
  colors: Colors;
467
  fontConfig: FontConfig;
468
  fonts: Fonts;
469
  fontSizes: FontSizes;
470
  fontWeights: FontWeights;
471
  letterSpacings: LetterSpacings;
472
  lineHeights: LineHeights;
473
  radii: Radii;
474
  space: Space;
475
  sizes: Sizes;
476
  components: ComponentThemes;
477
}
478

479
interface IV33xTheme extends V33xTheme {}
480
```