0
# Styling & Theming
1

2
Comprehensive theming system with design tokens, responsive styles, and media queries for consistent cross-platform styling.
3

4
## Capabilities
5

6
### Theme Hooks
7

8
React hooks for accessing and working with themes in components.
9

10
```typescript { .api }
11
/**
12
 * Access the current theme context
13
 * @param name - Optional theme name to use instead of current
14
 * @returns Theme object with design tokens
15
 */
16
function useTheme(name?: string): Theme;
17

18
/**
19
 * Get the current theme name
20
 * @returns Current theme name string
21
 */
22
function useThemeName(): string;
23

24
/**
25
 * Access Tamagui configuration within components
26
 * @returns Current Tamagui configuration
27
 */
28
function useConfiguration(): TamaguiInternalConfig;
29

30
interface Theme {
31
  [key: string]: string | Variable;
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import { useTheme, useThemeName, styled, View, Text } from "@tamagui/core";
39

40
function ThemedComponent() {
41
  const theme = useTheme();
42
  const themeName = useThemeName();
43
  
44
  return (
45
    <View style={{ backgroundColor: theme.background }}>
46
      <Text style={{ color: theme.color }}>
47
        Current theme: {themeName}
48
      </Text>
49
    </View>
50
  );
51
}
52

53
// Using specific theme
54
function SpecificThemeComponent() {
55
  const darkTheme = useTheme('dark');
56
  
57
  return (
58
    <View style={{ backgroundColor: darkTheme.background }}>
59
      <Text style={{ color: darkTheme.color }}>
60
        Always dark theme
61
      </Text>
62
    </View>
63
  );
64
}
65
```
66

67
### Media Query Hooks
68

69
Responsive design system with breakpoint detection and media query hooks.
70

71
```typescript { .api }
72
/**
73
 * Access current media query state for responsive design
74
 * @returns Object with boolean values for each media query
75
 */
76
function useMedia(): MediaState;
77

78
/**
79
 * Check if device has touch capability
80
 * @returns True if device supports touch
81
 */
82
function useIsTouchDevice(): boolean;
83

84
interface MediaState {
85
  [key: string]: boolean;
86
}
87

88
/**
89
 * Configure media queries for the application
90
 * @param media - Media query configuration
91
 */
92
function configureMedia(media: MediaConfig): void;
93

94
interface MediaConfig {
95
  [key: string]: {
96
    maxWidth?: number;
97
    minWidth?: number;
98
    maxHeight?: number;
99
    minHeight?: number;
100
  };
101
}
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
import { useMedia, styled, View } from "@tamagui/core";
108

109
function ResponsiveComponent() {
110
  const media = useMedia();
111
  
112
  return (
113
    <View>
114
      {media.sm && <Text>Small screen</Text>}
115
      {media.lg && <Text>Large screen</Text>}
116
    </View>
117
  );
118
}
119

120
// Responsive styled component
121
const ResponsiveContainer = styled(View, {
122
  padding: '$4',
123
  
124
  $sm: {
125
    padding: '$2',
126
    flexDirection: 'column',
127
  },
128
  
129
  $lg: {
130
    padding: '$6',
131
    flexDirection: 'row',
132
  },
133
});
134
```
135

136
### Token System
137

138
Design token access and manipulation functions.
139

140
```typescript { .api }
141
/**
142
 * Get a design token value by path
143
 * @param path - Token path (e.g., '$color.blue' or '$space.4')
144
 * @returns Token value
145
 */
146
function getToken(path: string): any;
147

148
/**
149
 * Get all design tokens
150
 * @returns Complete tokens object
151
 */
152
function getTokens(): TokensParsed;
153

154
/**
155
 * Get the resolved value of a token
156
 * @param token - Token variable or string
157
 * @returns Resolved token value
158
 */
159
function getTokenValue(token: string | Variable): any;
160

161
/**
162
 * Get all available themes
163
 * @returns Record of all theme definitions
164
 */
165
function getThemes(): Record<string, Theme>;
166

167
interface TokensParsed {
168
  color: Record<string, Variable>;
169
  space: Record<string, Variable>;
170
  size: Record<string, Variable>;
171
  radius: Record<string, Variable>;
172
  zIndex: Record<string, Variable>;
173
}
174
```
175

176
**Usage Examples:**
177

178
```typescript
179
import { getToken, getTokens, useTheme } from "@tamagui/core";
180

181
function TokenExample() {
182
  const blueColor = getToken('$color.blue');
183
  const spacing = getToken('$space.4');
184
  const allTokens = getTokens();
185
  
186
  return (
187
    <View style={{
188
      backgroundColor: blueColor,
189
      padding: spacing,
190
    }}>
191
      <Text>Using design tokens</Text>
192
    </View>
193
  );
194
}
195

196
// Using tokens in styled components
197
const TokenStyledView = styled(View, {
198
  backgroundColor: '$background',
199
  borderColor: '$borderColor',
200
  borderWidth: 1,
201
  borderRadius: '$radius.2',
202
  padding: '$space.4',
203
  margin: '$space.2',
204
});
205
```
206

207
### Theme Management
208

209
Functions for managing and updating themes dynamically.
210

211
```typescript { .api }
212
/**
213
 * Force update all theme-dependent components
214
 */
215
function forceUpdateThemes(): void;
216

217
/**
218
 * Update theme definitions at runtime
219
 * @param themes - New theme definitions to merge
220
 */
221
function updateThemes(themes: Record<string, Partial<Theme>>): void;
222

223
/**
224
 * Create a scoped theme provider component
225
 * @param name - Theme name
226
 * @param theme - Theme definition
227
 * @returns Theme provider component
228
 */
229
function createThemeProvider(name: string, theme: Theme): React.ComponentType<{
230
  children: React.ReactNode;
231
}>;
232
```
233

234
### Theme Component
235

236
Provider component for scoped theming within the component tree.
237

238
```typescript { .api }
239
/**
240
 * Scoped theme provider for applying themes to component subtrees
241
 */
242
declare const Theme: React.FC<ThemeProps>;
243

244
interface ThemeProps {
245
  /** Theme name to apply */
246
  name: string;
247
  /** Invert the current theme (light/dark toggle) */
248
  inverse?: boolean;
249
  /** Reset theme inheritance */
250
  reset?: boolean;
251
  /** Children components */
252
  children: React.ReactNode;
253
}
254
```
255

256
**Usage Examples:**
257

258
```typescript
259
import { Theme, View, Text } from "@tamagui/core";
260

261
function ScopedTheming() {
262
  return (
263
    <View>
264
      <Text>Default theme</Text>
265
      
266
      <Theme name="dark">
267
        <View backgroundColor="$background">
268
          <Text color="$color">Dark theme section</Text>
269
        </View>
270
      </Theme>
271
      
272
      <Theme inverse>
273
        <View backgroundColor="$background">
274
          <Text color="$color">Inverted theme section</Text>
275
        </View>
276
      </Theme>
277
    </View>
278
  );
279
}
280
```
281

282
### CSS Generation
283

284
Functions for generating CSS from themes and styles (primarily for web).
285

286
```typescript { .api }
287
/**
288
 * Generate CSS rules for themes
289
 * @param themes - Theme definitions
290
 * @returns CSS string with theme rules
291
 */
292
function getThemeCSSRules(themes: Record<string, Theme>): string;
293

294
/**
295
 * Insert CSS rules into the document
296
 * @param rules - CSS rules to insert
297
 * @param options - Insertion options
298
 */
299
function insertStyleRules(rules: string, options?: InsertRuleOptions): void;
300

301
/**
302
 * Wrap CSS styles in appropriate tags
303
 * @param css - CSS string to wrap
304
 * @param options - Wrapping options
305
 * @returns Wrapped CSS string
306
 */
307
function wrapStyleTags(css: string, options?: WrapOptions): string;
308

309
/**
310
 * Create media query specific styles
311
 * @param media - Media query definition
312
 * @param styles - Styles to apply
313
 * @returns Media query CSS string
314
 */
315
function createMediaStyle(media: string, styles: string): string;
316

317
interface InsertRuleOptions {
318
  priority?: number;
319
  media?: string;
320
}
321

322
interface WrapOptions {
323
  tag?: string;
324
  attributes?: Record<string, string>;
325
}
326
```
327

328
### Style Processing
329

330
Advanced style processing and normalization functions.
331

332
```typescript { .api }
333
/**
334
 * Split component props into style and non-style props
335
 * @param props - Component props
336
 * @param staticConfig - Component configuration
337
 * @param theme - Current theme
338
 * @param state - Component state
339
 * @param options - Processing options
340
 * @returns Split styles and props
341
 */
342
function getSplitStyles<T>(
343
  props: T,
344
  staticConfig: StaticConfig,
345
  theme: Theme,
346
  state: ComponentState,
347
  options?: GetStylesOptions
348
): SplitStyles;
349

350
/**
351
 * Expand shorthand style properties
352
 * @param styles - Style object with shorthands
353
 * @returns Expanded style object
354
 */
355
function expandStyles(styles: StyleObject): StyleObject;
356

357
/**
358
 * Get expanded shorthand properties
359
 * @param styles - Style object
360
 * @returns Expanded properties
361
 */
362
function getExpandedShorthands(styles: StyleObject): StyleObject;
363

364
/**
365
 * Generate atomic CSS classes
366
 * @param styles - Style object
367
 * @returns CSS classes and rules
368
 */
369
function getCSSStylesAtomic(styles: StyleObject): {
370
  classNames: string;
371
  rules: string[];
372
};
373

374
interface SplitStyles {
375
  style: StyleObject;
376
  classNames: string;
377
  pseudos: Record<string, StyleObject>;
378
  space: StyleObject;
379
  hasMedia: boolean;
380
}
381

382
interface GetStylesOptions {
383
  disableExpandShorthands?: boolean;
384
  resolveVariablesAs?: 'value' | 'variable' | 'auto';
385
}
386
```
387

388
### Color & Value Processing
389

390
Utilities for processing colors and style values.
391

392
```typescript { .api }
393
/**
394
 * Normalize color values across platforms
395
 * @param color - Color value to normalize
396
 * @returns Normalized color value
397
 */
398
function normalizeColor(color: any): string;
399

400
/**
401
 * Normalize style values with property-specific processing
402
 * @param value - Style value
403
 * @param property - CSS property name
404
 * @returns Normalized value
405
 */
406
function normalizeValueWithProperty(value: any, property: string): any;
407

408
/**
409
 * Normalize style object
410
 * @param styles - Style object to normalize
411
 * @returns Normalized style object
412
 */
413
function normalizeStyle(styles: StyleObject): StyleObject;
414
```
415

416
## Advanced Theming Patterns
417

418
### Dynamic Theme Creation
419

420
Create themes dynamically based on user preferences or system settings.
421

422
```typescript
423
import { createTamagui, getConfig, updateThemes } from "@tamagui/core";
424

425
function createUserTheme(preferences: UserPreferences) {
426
  const baseConfig = getConfig();
427
  
428
  const userTheme = {
429
    background: preferences.darkMode ? '#000000' : '#ffffff',
430
    color: preferences.darkMode ? '#ffffff' : '#000000',
431
    primary: preferences.accentColor,
432
    fontSize: preferences.fontSize,
433
  };
434
  
435
  updateThemes({
436
    user: userTheme,
437
  });
438
}
439
```
440

441
### Theme Inheritance
442

443
Themes can inherit from other themes for consistent variations.
444

445
```typescript
446
const themes = {
447
  light: {
448
    background: '$white',
449
    color: '$black',
450
    primary: '$blue',
451
  },
452
  dark: {
453
    background: '$black',
454
    color: '$white',
455
    primary: '$blue',
456
  },
457
  // Brand theme inheriting from light
458
  brand_light: {
459
    ...lightTheme,
460
    primary: '$brandColor',
461
    accent: '$brandAccent',
462
  },
463
};
464
```
465

466
### Conditional Theming
467

468
Apply themes based on conditions or user preferences.
469

470
```typescript
471
function ConditionalTheming({ userPrefersDark, children }) {
472
  const themeName = userPrefersDark ? 'dark' : 'light';
473
  
474
  return (
475
    <Theme name={themeName}>
476
      {children}
477
    </Theme>
478
  );
479
}
480
```
481

482
## Types
483

484
```typescript { .api }
485
interface Variable<T = any> {
486
  key: string;
487
  name: string;
488
  val: T;
489
  variable: string;
490
}
491

492
interface ComponentState {
493
  hover: boolean;
494
  press: boolean;
495
  focus: boolean;
496
}
497

498
interface StyleObject {
499
  [key: string]: any;
500
}
501
```