The @theme-ui/components package provides a complete set of primitive UI components that work seamlessly with your theme. All components support the sx prop and can be styled using theme values.
Installation
npm install @theme-ui/components @emotion/react
This package is included in the main theme-ui package, so a separate installation is not required if you’re already using theme-ui.
When to Use
Use @theme-ui/components when you:
- Need pre-built, theme-aware UI components
- Want consistent styling across your application
- Are building with design system constraints
- Need accessible, well-tested primitives
Use the umbrella theme-ui package if you also need the provider and other utilities.
All Components
Layout Components
Box
The foundational layout component. All other components are built on top of Box.
import { Box } from '@theme-ui/components'
<Box sx={{ padding: 3, bg: 'muted' }}>
Content
</Box>
Flex
A Box with display: flex.
import { Flex } from '@theme-ui/components'
<Flex sx={{ alignItems: 'center', gap: 2 }}>
<div>Item 1</div>
<div>Item 2</div>
</Flex>
Grid
A Box with display: grid.
import { Grid } from '@theme-ui/components'
<Grid columns={[1, 2, 3]} gap={3}>
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</Grid>
Container
A centered container with max-width.
import { Container } from '@theme-ui/components'
<Container>
Centered content
</Container>
Typography Components
Text
General purpose text component.
import { Text } from '@theme-ui/components'
<Text sx={{ fontSize: 2, color: 'text' }}>
Body text
</Text>
Heading
Heading component with automatic variant mapping.
import { Heading } from '@theme-ui/components'
<Heading as="h1">Page Title</Heading>
Paragraph
Paragraph component.
import { Paragraph } from '@theme-ui/components'
<Paragraph>Body paragraph text.</Paragraph>
Link
Styled link component.
import { Link } from '@theme-ui/components'
<Link href="/about">About</Link>
Form Components
Button
Button component with theme variants.
import { Button } from '@theme-ui/components'
<Button variant="primary">Click Me</Button>
Input
Text input field.
import { Input } from '@theme-ui/components'
<Input placeholder="Enter text" />
Textarea
Multi-line text input.
import { Textarea } from '@theme-ui/components'
<Textarea rows={4} placeholder="Enter text" />
Select
Dropdown select component.
import { Select } from '@theme-ui/components'
<Select>
<option>Option 1</option>
<option>Option 2</option>
</Select>
Label
Form label component.
import { Label } from '@theme-ui/components'
<Label htmlFor="email">Email Address</Label>
Checkbox
Checkbox input.
import { Checkbox } from '@theme-ui/components'
<Checkbox />
Radio
Radio button input.
import { Radio } from '@theme-ui/components'
<Radio name="option" value="1" />
Slider
Range slider input.
import { Slider } from '@theme-ui/components'
<Slider min={0} max={100} />
Switch
Toggle switch component.
import { Switch } from '@theme-ui/components'
<Switch />
Field
Combines Label and Input/Textarea/Select.
import { Field } from '@theme-ui/components'
<Field label="Email" name="email" />
Interactive Components
IconButton
Button optimized for icons.
import { IconButton } from '@theme-ui/components'
<IconButton aria-label="Menu">
<MenuIcon />
</IconButton>
import { MenuButton } from '@theme-ui/components'
<MenuButton aria-label="Toggle Menu" />
Close
Close button component.
import { Close } from '@theme-ui/components'
<Close onClick={handleClose} />
NavLink
Navigation link with active state support.
import { NavLink } from '@theme-ui/components'
<NavLink href="/about">About</NavLink>
Display Components
Card
Card container component.
import { Card } from '@theme-ui/components'
<Card>
Card content
</Card>
Image
Image component.
import { Image } from '@theme-ui/components'
<Image src="photo.jpg" alt="Description" />
Avatar
User avatar component.
import { Avatar } from '@theme-ui/components'
<Avatar src="avatar.jpg" />
Badge
Badge component for labels and counts.
import { Badge } from '@theme-ui/components'
<Badge>New</Badge>
Alert
Alert message component.
import { Alert } from '@theme-ui/components'
<Alert>Important message</Alert>
Message
Message box component.
import { Message } from '@theme-ui/components'
<Message>Information message</Message>
Divider
Horizontal divider.
import { Divider } from '@theme-ui/components'
<Divider />
Media Components
Embed
Responsive iframe embed.
import { Embed } from '@theme-ui/components'
<Embed src="https://www.youtube.com/embed/..." />
AspectRatio
Container that maintains aspect ratio.
import { AspectRatio } from '@theme-ui/components'
<AspectRatio ratio={16/9}>
Content
</AspectRatio>
AspectImage
Image with aspect ratio constraint.
import { AspectImage } from '@theme-ui/components'
<AspectImage ratio={4/3} src="photo.jpg" />
Feedback Components
Progress
Progress bar component.
import { Progress } from '@theme-ui/components'
<Progress max={100} value={75} />
Donut
Circular progress indicator.
import { Donut } from '@theme-ui/components'
<Donut value={0.75} />
Spinner
Loading spinner component.
import { Spinner } from '@theme-ui/components'
<Spinner />
Complete Component List
import {
// Layout
Box,
Flex,
Grid,
Container,
// Typography
Text,
Heading,
Paragraph,
Link,
// Forms
Button,
Input,
Textarea,
Select,
Label,
Checkbox,
Radio,
Slider,
Switch,
Field,
// Interactive
IconButton,
MenuButton,
Close,
NavLink,
// Display
Card,
Image,
Avatar,
Badge,
Alert,
Message,
Divider,
// Media
Embed,
AspectRatio,
AspectImage,
// Feedback
Progress,
Donut,
Spinner,
} from '@theme-ui/components'
Common Features
All components support:
The sx Prop
Style components with theme-aware values:
<Box sx={{
color: 'primary',
padding: 3,
fontSize: [1, 2, 3],
bg: 'muted'
}} />
Variants
Apply pre-defined style variants from your theme:
<Button variant="primary">Primary Button</Button>
<Button variant="secondary">Secondary Button</Button>
Responsive Props
Many components support responsive prop values:
<Grid columns={[1, 2, 3]} gap={[2, 3, 4]}>
{/* Content */}
</Grid>
TypeScript Support
All components are fully typed:
import type { BoxProps, ButtonProps, GridProps } from '@theme-ui/components'
Notes
- All components use the
sx prop for styling
- Components forward refs correctly
- Fully accessible with ARIA attributes
- Built with styled-system for consistent API
- Requires
@emotion/react and react as peer dependencies
- Requires
@theme-ui/theme-provider as a peer dependency
Related
