0
# @tamagui/core
1

2
@tamagui/core is a universal style library that serves as the foundational layer of the Tamagui ecosystem, providing cross-platform styling capabilities for React and React Native applications. It extends @tamagui/web with React Native-specific optimizations, enabling developers to write shared styling logic that works seamlessly across web and native platforms.
3

4
## Package Information
5

6
- **Package Name**: @tamagui/core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tamagui/core`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  TamaguiProvider, 
16
  createTamagui, 
17
  styled, 
18
  View, 
19
  Stack, 
20
  Text,
21
  useTheme,
22
  useMedia
23
} from "@tamagui/core";
24
```
25

26
For CommonJS:
27

28
```javascript
29
const { 
30
  TamaguiProvider, 
31
  createTamagui, 
32
  styled, 
33
  View, 
34
  Stack, 
35
  Text 
36
} = require("@tamagui/core");
37
```
38

39
## Basic Usage
40

41
```typescript
42
import { TamaguiProvider, createTamagui, styled, View, Text } from "@tamagui/core";
43

44
// 1. Configure Tamagui with tokens and themes
45
const config = createTamagui({
46
  tokens: {
47
    color: {
48
      blue: '#0066ff',
49
      white: '#ffffff',
50
    },
51
    space: {
52
      1: 4,
53
      2: 8,
54
      3: 16,
55
    },
56
  },
57
  themes: {
58
    light: {
59
      bg: '$white',
60
      color: '$blue',
61
    },
62
  },
63
  media: {
64
    sm: { maxWidth: 860 },
65
    lg: { minWidth: 980 },
66
  },
67
});
68

69
// 2. Create styled components
70
const Container = styled(View, {
71
  backgroundColor: '$bg',
72
  padding: '$3',
73
  
74
  variants: {
75
    centered: {
76
      true: {
77
        alignItems: 'center',
78
        justifyContent: 'center',
79
      }
80
    }
81
  }
82
});
83

84
const Title = styled(Text, {
85
  fontSize: 24,
86
  color: '$color',
87
  fontWeight: 'bold',
88
});
89

90
// 3. Use in your app
91
function App() {
92
  return (
93
    <TamaguiProvider config={config}>
94
      <Container centered>
95
        <Title>Hello Tamagui!</Title>
96
      </Container>
97
    </TamaguiProvider>
98
  );
99
}
100
```
101

102
## Architecture
103

104
@tamagui/core is built around several key systems:
105

106
- **Universal Components**: `View`, `Stack`, and `Text` components that work identically on web and React Native
107
- **Styling Engine**: `styled()` function for creating components with design tokens, variants, and responsive styles
108
- **Configuration System**: `createTamagui()` and `TamaguiProvider` for setting up design tokens, themes, and media queries
109
- **Cross-Platform Optimizations**: Atomic CSS generation for web, optimized native views for React Native
110
- **Type Safety**: Full TypeScript support with type inference for themes, tokens, and component props
111
- **React Native Enhancements**: Layout measurement, pressability handling, and platform-specific optimizations
112

113
## Capabilities
114

115
### Component Creation & Styling
116

117
Core component creation and styling capabilities for building reusable UI components with design tokens and variants.
118

119
```typescript { .api }
120
function styled<T extends React.ComponentType<any>>(
121
  component: T,
122
  config: StyledOptions
123
): TamaguiComponent;
124

125
interface StyledOptions {
126
  name?: string;
127
  variants?: VariantsConfig;
128
  defaultVariants?: DefaultVariants;
129
  [key: string]: any; // style properties
130
}
131
```
132

133
[Component Creation](./component-creation.md)
134

135
### Configuration & Setup
136

137
Configuration system for setting up design tokens, themes, media queries, and the Tamagui provider context.
138

139
```typescript { .api }
140
function createTamagui(config: TamaguiConfig): TamaguiInternalConfig;
141

142
interface TamaguiConfig {
143
  tokens?: Tokens;
144
  themes?: Record<string, Theme>;
145
  media?: MediaConfig;
146
  fonts?: FontConfig;
147
  animations?: AnimationConfig;
148
  shorthands?: ShorhandConfig;
149
  settings?: Settings;
150
}
151

152
declare const TamaguiProvider: React.FC<TamaguiProviderProps>;
153

154
interface TamaguiProviderProps {
155
  config: TamaguiInternalConfig;
156
  disableInjectCSS?: boolean;
157
  children?: React.ReactNode;
158
}
159
```
160

161
[Configuration & Setup](./configuration.md)
162

163
### Styling & Theming
164

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

167
```typescript { .api }
168
function useTheme(name?: string): Theme;
169
function useMedia(): MediaState;
170

171
function getToken(path: string): any;
172
function getTokens(): TokensParsed;
173

174
interface Theme {
175
  [key: string]: string | Variable;
176
}
177

178
interface MediaState {
179
  [key: string]: boolean;
180
}
181
```
182

183
[Styling & Theming](./styling-theming.md)
184

185
### React Native Features
186

187
React Native-specific enhancements including layout measurement, pressability handling, and platform optimizations.
188

189
```typescript { .api }
190
function useElementLayout(): LayoutState;
191
function setOnLayoutStrategy(strategy: LayoutStrategy): void;
192

193
interface LayoutEvent {
194
  nativeEvent: {
195
    layout: {
196
      x: number;
197
      y: number;
198
      width: number;
199
      height: number;
200
    };
201
  };
202
}
203

204
type LayoutStrategy = 'native' | 'web';
205
```
206

207
[React Native Features](./react-native-features.md)
208

209
### Utility Functions
210

211
Helper functions for style processing, event handling, and platform detection.
212

213
```typescript { .api }
214
function composeEventHandlers<T extends Function>(
215
  original?: T,
216
  next?: T
217
): T;
218

219
function getSplitStyles<T>(
220
  props: T,
221
  staticConfig: StaticConfig,
222
  theme: Theme,
223
  state: ComponentState,
224
  options?: GetStylesOptions
225
): SplitStyles;
226

227
// Platform detection constants
228
declare const isWeb: boolean;
229
declare const isServer: boolean;
230
declare const isClient: boolean;
231
declare const isAndroid: boolean;
232
declare const isIos: boolean;
233
declare const isTouchable: boolean;
234
```
235

236
[Utility Functions](./utilities.md)
237

238
## Core Components
239

240
### View Component
241

242
Universal view component with full React Native prop support and cross-platform styling.
243

244
```typescript { .api }
245
declare const View: TamaguiComponent<
246
  TamaDefer,
247
  TamaguiElement,
248
  RNTamaguiViewNonStyleProps,
249
  StackStyleBase,
250
  {}
251
>;
252

253
interface RNTamaguiViewNonStyleProps extends StackNonStyleProps, RNViewProps {}
254
```
255

256
### Stack Component  
257

258
Flexbox container component (alias for View) with column flex direction by default.
259

260
```typescript { .api }
261
declare const Stack: TamaguiComponent<
262
  TamaDefer,
263
  TamaguiElement,
264
  RNTamaguiViewNonStyleProps,
265
  StackStyleBase,
266
  {}
267
>;
268
```
269

270
### Text Component
271

272
Universal text component with React Native text props and typography variants.
273

274
```typescript { .api }
275
declare const Text: TamaguiComponent<
276
  TamaDefer,
277
  TamaguiTextElement,
278
  RNTamaguiTextNonStyleProps,
279
  TextStylePropsBase,
280
  {}
281
>;
282

283
interface RNTamaguiTextNonStyleProps extends TextNonStyleProps, RNTextProps {}
284
```
285

286
## Core Types
287

288
```typescript { .api }
289
interface TamaguiComponent<
290
  A = TamaDefer,
291
  B = TamaguiElement,
292
  C = {},
293
  D = {},
294
  E = {}
295
> extends React.ForwardRefExoticComponent<any> {
296
  staticConfig: StaticConfig;
297
}
298

299
interface StaticConfig {
300
  componentName?: string;
301
  variants?: any;
302
  defaultVariants?: any;
303
  accept?: any;
304
  isText?: boolean;
305
  isZStack?: boolean;
306
  validStyles?: any;
307
}
308

309
interface StackStyleBase {
310
  [key: string]: any;
311
}
312

313
interface TextStylePropsBase {
314
  [key: string]: any;
315
}
316

317
type TamaDefer = {};
318
type TamaguiElement = HTMLElement | React.ComponentType<any>;
319
type TamaguiTextElement = HTMLElement | React.ComponentType<any>;
320
```