0
# Configuration & Setup
1

2
Configuration system for setting up design tokens, themes, media queries, and the Tamagui provider context with React Native optimizations.
3

4
## Capabilities
5

6
### Create Tamagui Configuration
7

8
Main function to configure the Tamagui system with design tokens, themes, and platform optimizations.
9

10
```typescript { .api }
11
/**
12
 * Creates Tamagui configuration with automatic React Native media driver integration
13
 * @param config - Tamagui configuration object
14
 * @returns Internal configuration for TamaguiProvider
15
 */
16
function createTamagui(config: TamaguiConfig): TamaguiInternalConfig;
17

18
interface TamaguiConfig {
19
  /** Design tokens for consistent spacing, colors, typography */
20
  tokens?: Tokens;
21
  /** Theme definitions using tokens */
22
  themes?: Record<string, Theme>;
23
  /** Media query definitions for responsive design */
24
  media?: MediaConfig;
25
  /** Font configurations */
26
  fonts?: FontConfig;
27
  /** Animation configurations */
28
  animations?: AnimationConfig;
29
  /** CSS shorthand property mappings */
30
  shorthands?: ShorthandConfig;
31
  /** Framework settings and optimizations */
32
  settings?: Settings;
33
}
34

35
interface Tokens {
36
  /** Color tokens */
37
  color?: Record<string, string>;
38
  /** Spacing tokens */
39
  space?: Record<string, number>;
40
  /** Size tokens */
41
  size?: Record<string, number>;
42
  /** Radius tokens */
43
  radius?: Record<string, number>;
44
  /** Z-index tokens */
45
  zIndex?: Record<string, number>;
46
}
47

48
interface Theme {
49
  [key: string]: string | Variable;
50
}
51

52
interface MediaConfig {
53
  [key: string]: {
54
    maxWidth?: number;
55
    minWidth?: number;
56
    maxHeight?: number;
57
    minHeight?: number;
58
  };
59
}
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
import { createTamagui } from "@tamagui/core";
66

67
const config = createTamagui({
68
  tokens: {
69
    color: {
70
      white: '#ffffff',
71
      black: '#000000',
72
      blue: '#0066ff',
73
      gray: '#888888',
74
    },
75
    space: {
76
      1: 4,
77
      2: 8,
78
      3: 12,
79
      4: 16,
80
      5: 20,
81
      6: 24,
82
    },
83
    size: {
84
      sm: 24,
85
      md: 32,
86
      lg: 48,
87
      xl: 64,
88
    },
89
    radius: {
90
      1: 3,
91
      2: 6,
92
      3: 9,
93
      4: 12,
94
      round: 1000,
95
    },
96
  },
97
  
98
  themes: {
99
    light: {
100
      background: '$white',
101
      color: '$black',
102
      primary: '$blue',
103
      secondary: '$gray',
104
    },
105
    dark: {
106
      background: '$black',
107
      color: '$white',
108
      primary: '$blue',
109
      secondary: '$gray',
110
    },
111
  },
112
  
113
  media: {
114
    sm: { maxWidth: 860 },
115
    md: { maxWidth: 1020 },
116
    lg: { minWidth: 1020 },
117
    xl: { minWidth: 1280 },
118
  },
119
  
120
  fonts: {
121
    body: {
122
      family: 'Inter',
123
      size: {
124
        1: 12,
125
        2: 14,
126
        3: 16,
127
        4: 18,
128
        5: 20,
129
      },
130
      lineHeight: {
131
        1: 16,
132
        2: 20,
133
        3: 24,
134
        4: 26,
135
        5: 28,
136
      },
137
      weight: {
138
        normal: '400',
139
        bold: '700',
140
      },
141
    },
142
  },
143
  
144
  animations: {
145
    quick: {
146
      type: 'spring',
147
      damping: 20,
148
      mass: 1.2,
149
      stiffness: 250,
150
    },
151
  },
152
});
153
```
154

155
### Tamagui Provider
156

157
Root context provider that enables Tamagui styling throughout the React tree, with automatic element layout support for React Native.
158

159
```typescript { .api }
160
/**
161
 * Root provider component that enables Tamagui styling and automatic layout measurement
162
 * @param props - Provider configuration
163
 * @returns Provider component wrapping children
164
 */
165
declare const TamaguiProvider: React.FC<TamaguiProviderProps>;
166

167
interface TamaguiProviderProps {
168
  /** Tamagui configuration from createTamagui() */
169
  config: TamaguiInternalConfig;
170
  /** Theme name to use as default */
171
  defaultTheme?: string;
172
  /** Disable automatic CSS injection (web only) */
173
  disableInjectCSS?: boolean;
174
  /** Disable root theme class (web only) */
175
  disableRootThemeClass?: boolean;
176
  /** Children components */
177
  children?: React.ReactNode;
178
}
179
```
180

181
**Usage Examples:**
182

183
```typescript
184
import { TamaguiProvider, createTamagui } from "@tamagui/core";
185

186
const config = createTamagui({
187
  // configuration...
188
});
189

190
function App() {
191
  return (
192
    <TamaguiProvider config={config} defaultTheme="light">
193
      <YourAppContent />
194
    </TamaguiProvider>
195
  );
196
}
197

198
// Multiple themes
199
function AppWithThemes() {
200
  const [theme, setTheme] = useState('light');
201
  
202
  return (
203
    <TamaguiProvider config={config} defaultTheme={theme}>
204
      <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
205
        Toggle Theme
206
      </button>
207
      <YourAppContent />
208
    </TamaguiProvider>
209
  );
210
}
211
```
212

213
### Configuration Management
214

215
Functions for managing and accessing Tamagui configuration at runtime.
216

217
```typescript { .api }
218
/**
219
 * Set the global Tamagui configuration
220
 * @param config - Configuration to set
221
 */
222
function setConfig(config: TamaguiInternalConfig): void;
223

224
/**
225
 * Get the current global Tamagui configuration
226
 * @returns Current configuration
227
 */
228
function getConfig(): TamaguiInternalConfig;
229

230
/**
231
 * Safely get the current configuration (returns undefined if not set)
232
 * @returns Current configuration or undefined
233
 */
234
function getConfigMaybe(): TamaguiInternalConfig | undefined;
235

236
/**
237
 * Update existing configuration with new values
238
 * @param configUpdate - Partial configuration to merge
239
 */
240
function updateConfig(configUpdate: Partial<TamaguiConfig>): void;
241

242
/**
243
 * Get a specific setting value
244
 * @param key - Setting key to retrieve
245
 * @returns Setting value
246
 */
247
function getSetting(key: string): any;
248
```
249

250
### Token & Theme Creators
251

252
Utility functions for creating design tokens and themes with proper typing.
253

254
```typescript { .api }
255
/**
256
 * Create design tokens with type safety
257
 * @param tokens - Token definitions
258
 * @returns Processed tokens
259
 */
260
function createTokens<T extends Tokens>(tokens: T): TokensParsed;
261

262
/**
263
 * Create a single design token variable
264
 * @param value - Token value
265
 * @param options - Variable options
266
 * @returns Variable instance
267
 */
268
function createVariable<T>(value: T, options?: VariableOptions): Variable<T>;
269

270
/**
271
 * Create multiple design token variables
272
 * @param tokens - Token definitions
273
 * @returns Variable instances
274
 */
275
function createVariables<T extends Record<string, any>>(tokens: T): VariablesParsed<T>;
276

277
/**
278
 * Create a font configuration
279
 * @param font - Font definition
280
 * @returns Font configuration
281
 */
282
function createFont<T extends FontConfig>(font: T): T;
283

284
interface VariableOptions {
285
  key?: string;
286
  name?: string;
287
}
288

289
interface Variable<T = any> {
290
  key: string;
291
  name: string;
292
  val: T;
293
  variable: string;
294
}
295
```
296

297
### Development Setup
298

299
Functions for configuring development-time features and debugging.
300

301
```typescript { .api }
302
/**
303
 * Setup development mode with debugging and hot reload support
304
 * @param options - Development options
305
 */
306
function setupDev(options?: DevOptions): void;
307

308
interface DevOptions {
309
  /** Enable debug logging */
310
  debug?: boolean;
311
  /** Enable style inspection */
312
  visualizer?: boolean;
313
  /** Development server port */
314
  port?: number;
315
}
316
```
317

318
## Font Configuration
319

320
Comprehensive font system with cross-platform support.
321

322
```typescript { .api }
323
interface FontConfig {
324
  /** Font family name or stack */
325
  family: string;
326
  /** Font size tokens */
327
  size?: Record<string | number, number>;
328
  /** Line height tokens */
329
  lineHeight?: Record<string | number, number>;
330
  /** Font weight tokens */
331
  weight?: Record<string, string>;
332
  /** Letter spacing tokens */
333
  letterSpacing?: Record<string | number, number>;
334
  /** Font face definitions (web) */
335
  face?: FontFaceConfig[];
336
}
337

338
interface FontFaceConfig {
339
  /** Font family name */
340
  fontFamily: string;
341
  /** Font weight */
342
  fontWeight?: string;
343
  /** Font style */
344
  fontStyle?: string;
345
  /** Font source URL or local name */
346
  src: string;
347
}
348
```
349

350
**Usage Examples:**
351

352
```typescript
353
const fonts = {
354
  heading: {
355
    family: 'Inter, -apple-system, system-ui, sans-serif',
356
    size: {
357
      1: 12,
358
      2: 14,
359
      3: 16,
360
      4: 18,
361
      5: 20,
362
      6: 24,
363
      7: 28,
364
      8: 32,
365
      9: 36,
366
      10: 48,
367
    },
368
    lineHeight: {
369
      1: 17,
370
      2: 22,
371
      3: 25,
372
      4: 26,
373
      5: 28,
374
      6: 30,
375
      7: 35,
376
      8: 40,
377
      9: 44,
378
      10: 55,
379
    },
380
    weight: {
381
      normal: '400',
382
      bold: '700',
383
    },
384
    letterSpacing: {
385
      1: 0,
386
      2: -0.5,
387
    },
388
  },
389
};
390
```
391

392
## Animation Configuration
393

394
Cross-platform animation system configuration.
395

396
```typescript { .api }
397
interface AnimationConfig {
398
  [key: string]: AnimationDriver;
399
}
400

401
interface AnimationDriver {
402
  /** Animation type */
403
  type: 'spring' | 'timing' | 'decay';
404
  /** Spring configuration */
405
  damping?: number;
406
  mass?: number;
407
  stiffness?: number;
408
  /** Timing configuration */
409
  duration?: number;
410
  easing?: string;
411
  /** Decay configuration */
412
  deceleration?: number;
413
  velocity?: number;
414
}
415
```
416

417
## Settings
418

419
Framework-level settings and optimizations.
420

421
```typescript { .api }
422
interface Settings {
423
  /** Allow font scaling on native */
424
  allowFontScaling?: boolean;
425
  /** Animation driver to use */
426
  animationDriver?: string;
427
  /** Disable SSR warnings */
428
  disableSSR?: boolean;
429
  /** Default font */
430
  defaultFont?: string;
431
  /** Should attach debug data */
432
  shouldAddPrefersColorThemes?: boolean;
433
  /** Theme class names */
434
  themeClassNameOnRoot?: boolean;
435
  /** Maximum inline props */
436
  maxDarkLightNesting?: number;
437
}
438
```
439

440
## Types
441

442
```typescript { .api }
443
interface TamaguiInternalConfig {
444
  animations: AnimationConfig;
445
  fonts: Record<string, FontConfig>;
446
  media: MediaConfig;
447
  shorthands: ShorthandConfig;
448
  themes: Record<string, Theme>;
449
  tokens: TokensParsed;
450
  settings: Settings;
451
}
452

453
interface TokensParsed {
454
  color: Record<string, Variable>;
455
  space: Record<string, Variable>;
456
  size: Record<string, Variable>;
457
  radius: Record<string, Variable>;
458
  zIndex: Record<string, Variable>;
459
}
460

461
interface ShorthandConfig {
462
  [key: string]: string | string[];
463
}
464
```