Overview
The global.css file is the main entry point for Uniwind’s styling system. It’s where you import Tailwind and Uniwind, define theme-specific CSS variables, customize Tailwind’s configuration, and add global styles for your entire application.
The global.css file must be imported in your app’s entry point (usually App.tsx) for Uniwind to work correctly.
Required Imports
Every global.css file must include these two essential imports:
/* Required: Import Tailwind CSS */
@import 'tailwindcss';
/* Required: Import Uniwind */
@import 'uniwind';
- All Tailwind utility classes
- Uniwind’s React Native compatibility layer
- Theme-based variants (
dark:, light)
- Platform-specific variants (
ios:, android:, web:)
Customizing Tailwind Configuration
Use the @theme directive to customize Tailwind’s default configuration values:
Modifying Design Tokens
@import 'tailwindcss';
@import 'uniwind';
@theme {
/* Customize base font size */
--text-base: 15px;
/* Customize spacing scale */
--spacing-1: 4px;
--spacing-2: 8px;
--spacing-3: 12px;
--spacing-4: 16px;
/* Customize border radius */
--radius-sm: 4px;
--radius-md: 8px;
--radius-lg: 12px;
--radius-xl: 16px;
/* Add custom colors */
--color-primary: #3b82f6;
--color-secondary: #8b5cf6;
--color-accent: #ec4899;
}
Important: Variables in @theme only customize Tailwind utility classes. They do not apply globally to unstyled components. If you want to change the default font size for all Text components, you need to use className="text-base" on each component.
import { Text } from 'react-native'
// ❌ This will NOT use --text-base (uses React Native's default ~14px)
<Text>Unstyled text</Text>
// ✅ This WILL use --text-base (15px from your @theme)
<Text className="text-base">Styled text</Text>
Extending the Color Palette
@theme {
/* Add brand colors */
--color-brand-50: #eff6ff;
--color-brand-100: #dbeafe;
--color-brand-200: #bfdbfe;
--color-brand-300: #93c5fd;
--color-brand-400: #60a5fa;
--color-brand-500: #3b82f6;
--color-brand-600: #2563eb;
--color-brand-700: #1d4ed8;
--color-brand-800: #1e40af;
--color-brand-900: #1e3a8a;
}
<View className="bg-brand-500 text-white p-4" />
Theme-Specific Variables
Define different CSS variable values for each theme using the @layer theme directive with @variant:
Basic Theme Variables
@import 'tailwindcss';
@import 'uniwind';
@layer theme {
:root {
/* Dark theme variables */
@variant dark {
--color-background: #000000;
--color-foreground: #ffffff;
--color-muted: #374151;
--color-border: #1f2937;
}
/* Light theme variables */
@variant light {
--color-background: #ffffff;
--color-foreground: #000000;
--color-muted: #f3f4f6;
--color-border: #e5e7eb;
}
}
}
Complete Theme System
@import 'tailwindcss';
@import 'uniwind';
@layer theme {
:root {
@variant dark {
/* Backgrounds */
--color-background: #000000;
--color-background-secondary: #111827;
--color-card: #1f2937;
/* Text colors */
--color-foreground: #ffffff;
--color-foreground-secondary: #9ca3af;
--color-muted: #6b7280;
/* Borders */
--color-border: #374151;
--color-border-subtle: #1f2937;
/* Interactive elements */
--color-primary: #3b82f6;
--color-primary-hover: #2563eb;
--color-danger: #ef4444;
--color-success: #10b981;
--color-warning: #f59e0b;
}
@variant light {
/* Backgrounds */
--color-background: #ffffff;
--color-background-secondary: #f9fafb;
--color-card: #ffffff;
/* Text colors */
--color-foreground: #111827;
--color-foreground-secondary: #6b7280;
--color-muted: #9ca3af;
/* Borders */
--color-border: #e5e7eb;
--color-border-subtle: #f3f4f6;
/* Interactive elements */
--color-primary: #3b82f6;
--color-primary-hover: #2563eb;
--color-danger: #ef4444;
--color-success: #10b981;
--color-warning: #f59e0b;
}
}
}
OKLCH Color Support
Uniwind supports modern OKLCH color space, which provides more perceptually uniform colors and better color manipulation compared to traditional RGB/HSL:
@layer theme {
:root {
@variant dark {
--color-background: oklch(0.1316 0.0041 17.69);
--color-foreground: oklch(0.18 0.0033 17.46);
--color-primary: oklch(0 0 0);
--color-inverted: oklch(1 0 0);
--color-gray: oklch(0.452 0.0042 39.45);
}
@variant light {
--color-background: oklch(1 0 0);
--color-foreground: oklch(96.715% 0.00011 271.152);
--color-primary: oklch(1 0 0);
--color-inverted: oklch(0 0 0);
--color-gray: oklch(0.9612 0 0);
}
}
}
- Perceptually uniform: Colors that look equally bright to the human eye
- Wider color gamut: Access to more vibrant colors on modern displays
- Better interpolation: Smooth color transitions without muddy intermediate colors
- Consistent lightness: Easier to create accessible color palettes
Using Theme Variables
Once defined, reference your CSS variables directly as Tailwind utilities:
import { View, Text } from 'react-native'
export const ThemedCard = () => (
<View className="bg-card border border-border p-4 rounded-lg">
<Text className="text-foreground text-lg font-bold">
Card Title
</Text>
<Text className="text-foreground-secondary mt-2">
This card automatically adapts to the current theme
</Text>
</View>
)
No need to use var() or brackets! Simply use the variable name without the --color- prefix. For example, --color-primary becomes bg-primary or text-primary.
Custom Themes
Define variables for custom themes beyond light and dark:
@layer theme {
:root {
@variant dark {
--color-background: #000000;
--color-foreground: #ffffff;
}
@variant light {
--color-background: #ffffff;
--color-foreground: #000000;
}
/* Custom ocean theme */
@variant ocean {
--color-background: #0c4a6e;
--color-foreground: #e0f2fe;
--color-primary: #06b6d4;
--color-accent: #67e8f9;
}
/* Custom sunset theme */
@variant sunset {
--color-background: #7c2d12;
--color-foreground: #fef3c7;
--color-primary: #f59e0b;
--color-accent: #fb923c;
}
}
}
Static Theme Variables
If you need to define CSS variables that should always be available in JavaScript (via useCSSVariable) but aren’t used in any className, use the @theme static directive:
@import 'tailwindcss';
@import 'uniwind';
@theme static {
/* Chart-specific values */
--chart-line-width: 2;
--chart-dot-radius: 4;
--chart-grid-color: rgba(0, 0, 0, 0.1);
/* Custom brand colors not used in classNames */
--color-al-teal-10: #eaeeee;
--color-al-teal-25: #cad4d5;
--color-al-teal-75: #607d81;
--color-al-teal-100: #2b5257;
/* Native module configuration values */
--map-zoom-level: 15;
--animation-duration: 300;
}
When to Use Static Variables
Variables defined in @theme static are always available via the useCSSVariable hook, even if they’re never used in any className. @theme static for:
- Third-party library configuration: Values needed for chart libraries, maps, or other JavaScript APIs
- Runtime calculations: Design tokens used for JavaScript logic or animations
- Native module values: Configuration passed to native modules
- JavaScript-only values: Any CSS variable that should be accessible in JavaScript but doesn’t need to generate Tailwind utilities
Example: Using Static Variables
import { useCSSVariable } from 'uniwind'
import { LineChart } from 'react-native-chart-kit'
export const Chart = () => {
const lineWidth = useCSSVariable('--chart-line-width')
const dotRadius = useCSSVariable('--chart-dot-radius')
const gridColor = useCSSVariable('--chart-grid-color')
return (
<LineChart
data={data}
chartConfig={{
strokeWidth: lineWidth,
dotRadius: dotRadius,
color: () => gridColor,
}}
/>
)
}
You can use any valid CSS in global.css. For more information, check the CSS Parser documentation. Best Practices
Use semantic variable names: Name variables based on their purpose (e.g., --color-background, --color-primary) rather than their value (e.g., --color-blue-500).
Keep theme variables consistent: Ensure all themes define the same set of variables. If you miss a variable in one theme, we will warn you about it in __DEV__ mode.
Avoid hard-coded colors in components: Use CSS variables for colors that should adapt to themes. This ensures your UI remains consistent across theme changes.
