useStyles(config, props)

useStyles() is a composable React hook that generates CSS styles based on your component's input props. For a deep dive into creating a style hook from scratch, check out the Create a Style Hook tutorial.

Arguments

  • config <object> required

    This argument configures your component's style props and connects your component to the theme if you're using one. It should contain two properties name and styles

    • name <string> required

      This is the key name you'll use for this hook when configuring it in your theme. As such, it should be unique. Names are important because they allow your hook to use powerful features like the kind prop anddefaultProps in your theme. They also provide organization to your theme allowing you to provide a name argument to useTheme('name').

    • styles <object> required

      This is the object that defines your component's style props. The key names of this object become prop names in your component and the value handles the creation of style definitions. See creating style props below to learn the numerous ways you can generate styles.

  • props <object> required

    props allude to, as you'd guess, the props object provided to an element when it is created with React.createElement(). But it can be any plain object you want to derive styles from. useStyles() is an immutable function. That is, the input props are cloned and the return value is a new object containing a css prop with your generated styles. It will also remove any keys from the input props that generated styles.

    For example, let's say your component has a boolean style prop for hidden which provides a display: none; style:

    // Given the input props
    {hidden: true, foo: 'bar'}
    // Expect the output props
    {
    foo: 'bar',
    css: [{
    name: "1ecy55y",
    styles: "display: none;"
    }]
    }

Creating style props

There are three ways to create style props in a useStyles() hook

  1. Creating a boolean style prop

    This is the most basic type of style prop you can create. To use it, create a key in your styles object that has an Emotion css object as its value.

    import {css} from '@emotion/core'
    // style definitions
    const styles = {
    // this creates a `boolean` prop for `hidden`
    hidden: css`display: none;`
    }
    // ... add your hook MyComponent ... //
    <MyComponent hidden/>
    // Here, the prop `hidden` becomes
    // {css: [{name: '...', styles: 'display: none;'}]}
  2. Creating an enum style prop

    To construct an enum style prop just use the same pattern we used for a boolean prop, but as part of a nested object.

    import {css} from '@emotion/core'
    // style definitions
    const styles = {
    // this creates an `enum` prop for `display`
    // with the choices 'none', 'block', and 'flex'
    display: {
    none: css`display: none;`,
    block: css`display: block;`,
    flex: css`display: flex;`,
    }
    }
    // ... add your hook MyComponent ... //
    <MyComponent display='block'/>
    // Here, the prop `display` becomes
    // {css: [{name: '...', styles: 'display: block;'}]}
  3. Creating a functional style prop

    The true magic begins when you create functional style props. Here we can customize our styles based on the component theme and props passed to the useStyles() hook. Return an Emotion css object to add styles, or null/undefined to skip adding styles.

    Here is the function signature

    (value: <any>, theme: <object>, props: <object>) => <css|void>

    • value <any>

      The value provided to the style prop in React.createElement().

    • theme <object>

      The theme as defined in ThemeProvider.

    • props <object>

      Other props that were passed to our useStyles() hook.

    import {css} from '@emotion/core'
    // fake default theme
    const theme = {
    box: {
    sizes: {
    sm: 16,
    md: 32,
    lg: 64
    }
    }
    }
    // style definitions
    const styles = {
    // this creates a `functional` prop for `size`
    size: (value, theme, props) => {
    const px = theme.box.sizes[value]
    // in reality you'd throw an error, but for this example
    // we just skip the prop
    if (px === undefined)
    return
    return css`
    width: ${px}px;
    height: ${px}px;
    `
    }
    }
    // ... add your hook MyComponent ... //
    <MyComponent size='md'/>
    // Here, the prop `size` becomes
    // {css: [{name: '...', styles: 'width: 32px; height: 32px;'}]}

Example useBox() hook

Below is an example hook from the Create a Style Hook tutorial.

Continue to createElement()