Theming

Smooth UI is entirely configurable from the theme. It uses Styled Components theming feature or emotion-theming under the hood. You can customize nearly anything using the theme!

Theme engine

Smooth UI relies on styled-components theming and emotion theming that works similarly. If you already use it in your application, it will work out of the box!

Theme specification

Smooth UI uses xstyled that implements a powerful theme specification.

All system properties are binded to the theme, it really gives super powers!

Use a custom theme

You can use the ThemeProvider provided by styled-components or emotion-theming. You must set your provider up before any Smooth UI component.

Hello world
import React from 'react'
import { ThemeProvider } from 'styled-components'
import { Button } from '@smooth-ui/core-sc'

const theme = {
  colors: {
    primary: 'blue',
  },
}

function Example() {
  return <Button>Hello world</Button>
}

render(
  <ThemeProvider theme={theme}>
    <Example />
  </ThemeProvider>,
)
import React from 'react'
import { ThemeProvider } from 'styled-components'
import { Button } from '@smooth-ui/core-sc'
const theme = {
  colors: {
    primary: 'blue',
  },
}
function Example() {
  return <Button>Hello world</Button>
}
render(
  <ThemeProvider theme={theme}>
    <Example />
  </ThemeProvider>,
)

Default theme

Smooth UI automatically merges its default theme in components. If you want to use Smooth UI theme in your application you can import it directly from @smooth-ui/core-sc or @smooth-ui/core-em.

All theme values are in the code.

import { theme } from '@smooth-ui/core-sc'
import { ThemeProvider } from 'styled-components'
import App from './App'
render(
  <ThemeProvider theme={theme}>
    <App />
  </ThemeProvider>,
)

Use theme in properties

@xstyled/system is implemented in all components, your theme value can be used in any of them.

For example, you can define the background color of a button with a property:

Hello world
import React from 'react'
import { ThemeProvider } from 'styled-components'
import { Button } from '@smooth-ui/core-sc'

const theme = {
  colors: {
    awesomeColor: 'violet',
  },
}

function Example() {
  return <Button backgroundColor="awesomeColor">Hello world</Button>
}

render(
  <ThemeProvider theme={theme}>
    <Example />
  </ThemeProvider>,
)
import React from 'react'
import { ThemeProvider } from 'styled-components'
import { Button } from '@smooth-ui/core-sc'
const theme = {
  colors: {
    awesomeColor: 'violet',
  },
}
function Example() {
  return <Button backgroundColor="awesomeColor">Hello world</Button>
}
render(
  <ThemeProvider theme={theme}>
    <Example />
  </ThemeProvider>,
)

To learn more about system properties, see xstyled system properties.

Build components with theme

@xstyled/system provides lot of utilities to access the theme in your components.

For example, you can use th to access a theme property:

import { th } from '@xstyled/system'
const RedBox = styled.div`
  background-color: ${th.color('primary')};
`

To learn more about system components, see xstyled system utilities.

Theme reference

Smooth UI also supports theme reference, using th you can refer to another theme value without repeating it:

// theme.js
import { th } from '@xstyled/system'
export const colors = {
  blue: '#00bdff',
  // primary is now a reference to `blue`
  primary: th.color('blue'),
}