このスキルは、基本的なものを超えた Tamagui v1.x のパターンを提供します。Config v4、コンパイラ最適化、複合コンポーネント、よくある間違いに焦点を当てています。
必須コンテキスト読み込み
これらのコンポーネントを扱う際は、コードを書く前に対応するパターンファイルを読んでください:
| コンポーネントタイプ | 必須読み込みファイル | クロススキル |
|---|---|---|
| Dialog, Sheet, モーダルオーバーレイ | @DIALOG_PATTERNS.md | |
| Form, Input, Label, バリデーション | @FORM_PATTERNS.md | typescript-best-practices (zod) |
| アニメーション, トランジション | @ANIMATION_PATTERNS.md | |
| Popover, Tooltip, Select | @OVERLAY_PATTERNS.md | |
| コンパイラ最適化 | @COMPILER_PATTERNS.md | |
| デザイントークン, テーマ設定 | @DESIGN_SYSTEM.md |
Config v4 クイックスタート
簡略化されたセットアップには @tamagui/config/v4 を使用します:
// tamagui.config.ts
import { defaultConfig } from '@tamagui/config/v4'
import { createTamagui } from 'tamagui'
export const config = createTamagui(defaultConfig)
type CustomConfig = typeof config
declare module 'tamagui' {
interface TamaguiCustomConfig extends CustomConfig {}
}
推奨設定(flexBasis を React Native に合わせる場合):
export const config = createTamagui({
...defaultConfig,
settings: {
...defaultConfig.settings,
styleCompat: 'react-native',
},
})
createThemes パターン
カスタムテーマには、パレット/アクセント/子テーマとともに createThemes を使用します:
import { createThemes, defaultComponentThemes } from '@tamagui/config/v4'
const generatedThemes = createThemes({
componentThemes: defaultComponentThemes,
base: {
palette: {
dark: ['#050505', '#151515', /* ...12色 */ '#fff'],
light: ['#fff', '#f8f8f8', /* ...12色 */ '#000'],
},
extra: {
light: { ...Colors.blue, shadowColor: 'rgba(0,0,0,0.04)' },
dark: { ...Colors.blueDark, shadowColor: 'rgba(0,0,0,0.2)' },
},
},
accent: {
palette: { dark: lightPalette, light: darkPalette }, // 反転
},
childrenThemes: {
blue: { palette: { dark: Object.values(Colors.blueDark), light: Object.values(Colors.blue) } },
red: { /* ... */ },
green: { /* ... */ },
},
})
トークンとテーマの構文
$ プレフィックスのルール
- プロップ: トークン参照には
$プレフィックスを使用します:<Text color="$color" fontSize="$4" /> - テーマキー: テーマ定義内では
$なしでアクセスします:{ color: palette[11] } - バリアント内のトークンアクセス:
tokens.size[name]パターンを使用します
バリアントスプレッド演算子
特別なスプレッド演算子は、トークンカテゴリをバリアント値にマッピングします:
const Button = styled(View, {
variants: {
size: {
// size トークンをマッピング: $1, $2, $true など
'...size': (size, { tokens }) => ({
height: tokens.size[size] ?? size,
borderRadius: tokens.radius[size] ?? size,
gap: tokens.space[size]?.val * 0.2,
}),
},
textSize: {
// fontSize トークンをマッピング
'...fontSize': (name, { font }) => ({
fontSize: font?.size[name],
}),
},
} as const,
})
重要: TypeScript が推論された const ジェネリクスをサポートするまで、variants オブジェクトには as const を使用してください。
createStyledContext による複合コンポーネント
<Button><Button.Text>Click</Button.Text></Button> のような複合 API の場合:
import {
SizeTokens,
View,
Text,
createStyledContext,
styled,
withStaticProperties,
} from '@tamagui/core'
// 1. 共有バリアントタイプを持つコンテキストを作成
const ButtonContext = createStyledContext<{ size: SizeTokens }>({
size: '$medium',
})
// 2. コンテキストを持つフレームを作成
const ButtonFrame = styled(View, {
name: 'Button',
context: ButtonContext,
variants: {
size: {
'...size': (name, { tokens }) => ({
height: tokens.size[name],
borderRadius: tokens.radius[name],
gap: tokens.space[name].val * 0.2,
}),
},
} as const,
defaultVariants: {
size: '$medium',
},
})
// 3. 同じコンテキストを持つテキストを作成(バリアントは自動同期)
export const ButtonText = styled(Text, {
name: 'ButtonText',
context: ButtonContext,
variants: {
size: {
'...fontSize': (name, { font }) => ({
fontSize: font?.size[name],
}),
},
} as const,
})
// 4. withStaticProperties で合成
export const Button = withStaticProperties(ButtonFrame, {
Props: ButtonContext.Provider,
Text: ButtonText,
})
使用法:
<Button size="$large">
<Button.Text>Click me</Button.Text>
</Button>
// または上からデフォルトをオーバーライド:
<Button.Props size="$small">
<Button><Button.Text>Small</Button.Text></Button>
</Button.Props>
注意: context パターンはコンパイラのフラット化では機能しません。高レベルコンポーネント(Button, Card)には使用し、プリミティブ(Stack, Text)には使用しないでください。
ラッパーコンポーネントのための styleable()
関数コンポーネントでスタイル付きコンポーネントをラップする場合は、.styleable() を使用してバリアントの継承を維持します:
const StyledText = styled(Text)
// styleable なし - 壊れたバリアント継承
const BrokenWrapper = (props) => <StyledText {...props} />
// styleable あり - 正しい
const CorrectWrapper = StyledText.styleable((props, ref) => (
<StyledText ref={ref} {...props} />
))
// これで動作します:
const StyledCorrectWrapper = styled(CorrectWrapper, {
variants: {
bold: { true: { fontWeight: 'bold' } },
},
})
追加のプロップを追加
追加のプロップについては、ジェネリック型引数を渡します:
type ExtraProps = { icon?: React.ReactNode }
const IconText = StyledText.styleable<ExtraProps>((props, ref) => {
const { icon, ...rest } = props
return (
<XStack>
{icon}
<StyledText ref={ref} {...rest} />
</XStack>
)
})
カスタムコンポーネントのための accept プロップ
非標準のプロップでトークン/テーマの解決を有効にします:
// テーマカラーを受け入れるべき SVG の fill/stroke の場合
const StyledSVG = styled(SVG, {}, {
accept: { fill: 'color', stroke: 'color' } as const,
})
// 使用法: <StyledSVG fill="$blue10" />
// style オブジェクト(ScrollView の contentContainerStyle など)の場合
const MyScrollView = styled(ScrollView, {}, {
accept: { contentContainerStyle: 'style' } as const,
})
// 使用法: <MyScrollView contentContainerStyle={{ padding: '$4' }} />
重要: accept オブジェクトには as const を使用してください。
プロップの順序が重要
styled() 内では、プロップの順序がオーバーライドの優先順位を決定します:
// backgroundColor はプロップによってオーバーライド可能
const Overridable = (props) => (
<View backgroundColor="$red10" {...props} width={200} />
)
// width はオーバーライド不可(スプレッドより後にあるため)
// バリアントの順序も重要:
<Component scale={3} huge /> // scale = 3 (scale が先)
<Component huge scale={3} /> // scale = 2 (huge がオーバーライド)
アンチパターン
動的スタイルは最適化を壊す
// 悪い例 - コンパイラ最適化を壊す
<View style={{ width: someVariable * 2 }} />
<View backgroundColor={isDark ? '$gray1' : '$gray12'} />
// 良い例 - バリアントを使用
const Box = styled(View, {
variants: {
dark: { true: { backgroundColor: '$gray1' }, false: { backgroundColor: '$gray12' } },
},
})
<Box dark={isDark} />
インライン関数
// 悪い例 - レンダリングごとに新しい関数
<View onPress={() => handlePress(id)} />
// 良い例 - 安定した参照
const handlePressCallback = useCallback(() => handlePress(id), [id])
<View onPress={handlePressCallback} />
誤ったインポートパス
// これらは異なるパッケージであり、内容が異なります:
import { View } from 'tamagui' // 完全な UI キット
import { View } from '@tamagui/core' // コアのみ(より小さい)
import { Button } from '@tamagui/button' // 個別コンポーネント
// 一つのアプローチを選び、一貫性を保つ
RN StyleSheet と Tamagui の混在
// 悪い例 - StyleSheet の値はトークンを解決しない
const styles = StyleSheet.create({ box: { padding: 20 } })
<View style={styles.box} backgroundColor="$blue10" />
// 良い例 - すべて Tamagui
<View padding="$4" backgroundColor="$blue10" />
Dialog/Sheet のための Platform.OS 分岐
// 悪い例 - 手動プラットフォーム分岐
if (Platform.OS === 'web') {
return <Dialog>...</Dialog>
}
return <Sheet>...</Sheet>
// 良い例 - Adapt を使用(@DIALOG_PATTERNS.md 参照)
<Dialog>
<Dialog.Portal>...</Dialog.Portal>
<Adapt when="sm" platform="touch">
<Sheet><Adapt.Contents /></Sheet>
</Adapt>
</Dialog>
最新ドキュメントの取得
最新のAPI詳細については、マークダウンドキュメントを直接取得してください:
# コアドキュメント
curl -sL "https://tamagui.dev/docs/core/configuration.md"
curl -sL "https://tamagui.dev/docs/core/styled.md"
curl -sL "https://tamagui.dev/docs/core/variants.md"
curl -sL "https://tamagui.dev/docs/core/animations.md"
# コンポーネントドキュメント
curl -sL "https://tamagui.dev/ui/sheet.md"
curl -sL "https://tamagui.dev/ui/dialog.md"
curl -sL "https://tamagui.dev/ui/select.md"
# 全ドキュメントインデックス
curl -sL "https://tamagui.dev/llms.txt"
HTMLページの場合は、適切なセレクタを指定して web-fetch スキルを使用してください。
クイックリファレンス
Config v4 ショートハンド(Tailwind 準拠)
| ショートハンド | プロパティ |
|---|---|
bg | backgroundColor |
p | padding |
m | margin |
w | width |
h | height |
br | borderRadius |
メディアクエリブレークポイント
| トークン | デフォルト | サーバーデフォルト |
|---|---|---|
$xs | 660px | true |
$sm | 800px | false |
$md | 1020px | false |
$lg | 1280px | false |
$xl | 1420px | false |
アニメーションドライバー
| ドライバー | プラットフォーム | ユースケース |
|---|---|---|
css | Web | デフォルト、最高のパフォーマンス |
react-native-reanimated | ネイティブ | ネイティブアニメーションに必須 |
追加パターンファイル
- @DIALOG_PATTERNS.md - Dialog, Sheet, Adapt, アクセシビリティ
- @FORM_PATTERNS.md - Form, Input, Label, zod によるバリデーション
- @ANIMATION_PATTERNS.md - アニメーションドライバー, enterStyle/exitStyle
- @OVERLAY_PATTERNS.md - Popover, Tooltip, Select
- @COMPILER_PATTERNS.md - コンパイラ最適化の詳細
- @DESIGN_SYSTEM.md - デザイントークンとテーマ設定