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
```