title |
---|
Getting Started |
Install Theme UI.
npm i theme-ui
Create a theme object to include custom color, typography, and layout values.
// example theme.js
export default {
fonts: {
body: 'system-ui, sans-serif',
heading: '"Avenir Next", sans-serif',
monospace: 'Menlo, monospace',
},
colors: {
text: '#000',
background: '#fff',
primary: '#33e',
},
}
If you’re using Gatsby, see the Getting Started with Gatsby page.
Add the theme to your application with the ThemeProvider
, passing in the theme
object as a prop.
// basic usage
import { ThemeProvider } from 'theme-ui'
import theme from './theme'
export default (props) => (
<ThemeProvider theme={theme}>{props.children}</ThemeProvider>
)
Use the sx
prop throughout your application to add styles based on your theme to any component.
Enable the sx
prop by adding the /** @jsxImportSource theme-ui */
comment to the top of your file.
The sx
prop lets you add any valid CSS to an element,
while using values from your theme to keep styles consistent.
You can think of the style object that the sx
prop accepts as a superset of CSS.
/** @jsxImportSource theme-ui */
export default (props) => (
<div
sx={{
fontWeight: 'bold',
fontSize: 4, // picks up value from `theme.fontSizes[4]`
color: 'primary', // picks up value from `theme.colors.primary`
}}>
Hello
</div>
)
Confused about this @jsxImportSource
comment? Read more about JSX Pragma.
If you use the classic JSX runtime, the /** @jsxImportSource theme-ui */
comment has no effect.
In this case enable the sx
prop by adding the /** @jsx jsx */
comment instead and importing jsx
from Theme UI.
/** @jsx jsx */
import { jsx } from 'theme-ui'
The sx
prop also supports using arrays as values to change properties responsively with a mobile-first approach.
/** @jsxImportSource theme-ui */
export default (props) => (
<div
sx={{
// applies width 100% to all viewport widths,
// width 50% above the first breakpoint,
// and 25% above the next breakpoint
width: ['100%', '50%', '25%'],
}}
/>
)
This API originated in Styled System and is intended as a terser syntax for applying responsive styles across a singular dimension.
The values used for media queries can be defined in a theme.breakpoints
array.
If you prefer standard CSS syntax, you can use nested objects for responsive styles as well.
<div
sx={{
width: '100%',
'@media screen and (min-width: 40em)': {
width: '50%',
},
}}
/>
Theme UI includes a library of primitive UI components, which can be completely customized with your theme and include support for variants. You can use variants to encapsulate more complex, component-specific styles that can be changed with props. Import and use these components to handle layout, images, forms, and more.
/** @jsxImportSource theme-ui */
import { Box, Label, Input, Button } from 'theme-ui'
export default (props) => (
<Box sx={{ mb: 4 }}>
<Label htmlFor="search">Search</Label>
<Input id="search" name="search" {...props} />
<Button>Go</Button>
</Box>
)
See the Components documentation for more.