Lorem

Understanding Theme UI: 6 - The Hacks

In this post i’m going to explain some of my Theme UI “hacks”… to be honest they’re not really hacks but you won’t necessarily find these in the docs since they mostly relate to standard CSS selectors but it wasn’t immediately obvious to me that the sx prop can be used in this way.

If you’re new to Theme UI i’d suggest having a read of the first five posts in this series to bring you up to speed

Variants - Buttons

There are some obvious uses for variants that are explained in the docs but one method I use a fair bit isn’t covered by the docs so here’s one way you can use variants inside the theme object.

Below is a method I use for styling button variants and as the docs mention the default variant is theme.buttons.primary. You’ll see in the source below that if the <Button /> component is used without a variant prop it’ll default to the styles in defined in theme.buttons.primary

Src 👇

<Button>Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="ghost">Ghost</Button>

Theme 👇

// path-to-theme/index.js

export default {
  colors: {
    text: '#FFFFFF',
    muted: '#8b87ea',
    primary: '#f056c7',
    secondary: '#c39eff',
    background: '#131127',
  },
  buttons: {
    primary: {
      backgroundColor: 'primary',
      borderRadius: 0,
      color: 'text',
      cursor: 'pointer',
      minWidth: 120,
      px: 3,
      py: 2,
    },
    secondary: {
      variant: 'buttons.primary',
      color: 'background',
      backgroundColor: 'secondary',
    },
    ghost: {
      variant: 'buttons.primary',
      color: 'muted',
      backgroundColor: 'background',
    },
  },
};

To create alternative button variants I define them in the same buttons object and give each one a name. e.g “secondary” and “ghost”.

Like in normal CSS you’ll want the additional button variants to extend the default class, in this case it’s called “primary” this is so you don’t have to re-define or duplicate CSS properties for the padding, min-with etc and the way to do this in Theme UI is to use the variant “prop” inside the theme object.

Looking at the object for secondary you’ll notice it has a variant of buttons.primary this means it’ll extend all the CSS properties from the default button and will then apply / overwrite new CSS properties for it’s color and backgroundColor. You can use this approach for as many button variants as you require, but do always “extend” using the variant before applying new styles.

Variants - typography

This one is a bit gnarly so strap in. The concept here is that the variant prop used on the component can be used to point to a specific set of styles in the theme, this can be any theme key, in the below example it’s styles and as seen in the button example above you can also extend from a theme object using the variant key

Src 👇

<Heading as='h3' variant='styles.h3'>Heading h3</Heading>
<Heading as='h4' variant='styles.h4'>Heading h4</Heading>

Theme 👇

// path-to-theme/index.js

export default {
  fonts: {
    heading: 'Inconsolata, monospace',
  },
  fontSizes: [12, 16, 18],
  text: {
    heading: {
      fontFamily: 'heading',
      fontSize: 2,
    },
  },
  styles: {
    h3: {
      variant: 'text.heading',
      color: 'secondary',
    },
    h4: {
      variant: 'text.heading',
      color: 'text',
    },
  },
};

First thing to note with typography is that you’ll most likely want to use the as prop to determine the HTML dom node, but… this doesn’t automatically mean HTML dom nodes map to styles. As an aside it’s quite possible you’ll want to style h(n) tags differently on different pages and by de-coupling as from variant is quite handy albeit a bit complicated to grasp at first.

With that out of the way we can move on to variants.

You’ll see above in the above <Heading as='h3' variant='styles.h3'/> I map the variant to styles.h3 and if you look at the theme object for styles.h3 it first extends the styles defined in text.heading and then applies a new CSS property for color.

These styles are from my theme: gatsby-theme-terminal and the typography treatments are quite simple but hopefully you can see from the above how to map from component usage to a theme key using the variant prop and from there you can extend from another theme key.

If you’re coming to Theme UI from .scss it’s a bit like @extend and if you’re coming from css-modules it’s a bit like composes

FYI The reason I point typography to styles is because the styles key is what Theme UI uses when styling HTML dom nodes found in markdown (.md) or MDX (.mdx)

CSS selectors

Every now and then you might run into an issue where you’ll need to target a sibling or child of a Theme UI component.

I had this recently when I used the Reach UI - menu-button. For the purposes of an example i’ve removed a lot of the code but the TLDR is that you can style any sibling or child from the sx prop using normal CSS selectors

To target a child by id you can do this 👇

<Box
  sx={{
    '#menu--1': {
      borderColor: 'primary',
      borderStyle: 'solid',
      borderWidth: '1px',
    },
  }}
>
  <div id='menu--1'>...</div>
</Box>

To target a child by class you can do this 👇

<Box
  sx={{
    '.menu': {
      borderColor: 'primary',
      borderStyle: 'solid',
      borderWidth: '1px',
    },
  }}
>
  <div className='menu'>...</div>
</Box>

To target a child by data- attribute you can do this 👇

<Box
  sx={{
    '[data-reach-menu-list="menu"]': {
      borderColor: 'primary',
      borderStyle: 'solid',
      borderWidth: '1px',
    },
  }}
>
  <div data-reach-menu-list='menu'>...</div>
</Box>

To target an adjacent sibling by class you can do this 👇

<Box
  sx={{
    '+ .menu': {
      borderColor: 'primary',
      borderStyle: 'solid',
      borderWidth: '1px',
    },
  }}
/>
<div className="menu">...</div>

To target a general sibling by class you can do this 👇

<Box
  sx={{
    '~ .menu': {
      borderColor: 'primary',
      borderStyle: 'solid',
      borderWidth: '1px',
    },
  }}
/>
<div className="menu">...</div>
<div className="menu menu-items">...</div>

I’ve written a post about how to use “style objects” for use with Styled Components but the same approach works with Theme UI. You can read more about “style objects” in this post: [Styled Components Style Objects](/posts/2020/08/Styled Components-style-objects/)

SVG paths

One “hack” I used extensively in BumHub was to target the SVG’s <path> tags via a className to set their fill to colors defined in the theme. This way if you change any color values for use around your site all your SVG’s will update the same as any other HTML dom nodes.

the colors seen below are inherited from the theme used in this blog

import React from 'react';
import { Box } from 'theme-ui';

export const LogoIcon = () => {
  return (
    <Box
      as='svg'
      sx={{
        '.logo-outline': {
          fill: 'surface',
        },
        '.logo-solid': {
          fill: 'primary',
        },
        '.logo-detail': {
          fill: 'text',
        },
      }}
    >
      <g>
        <path className='logo-solid' d='...' />
        <g className='logo-detail'>
          <path d='...' />
          <path d='...' />
          <path d='...' />
          <path d='...' />
          <path d='...' />
        </g>

        <path className='logo-outline' d='...' />
      </g>
    </Box>
  );
};

css keyframes

This is a lesser understood part of CSS and arguably even more so with Theme UI as it’s not mentioned in the docs anywhere. However it is possible to animate using CSS keyframes using keyframes from @emotion/react

To help demonstrate how keyframes work here’s a very simple loading component called <MrKeyframes /> and you can find the src here

import React from 'react';
import { Box, Grid } from 'theme-ui';
import { keyframes } from '@emotion/react';

export const MrKeyframes = () => {
  const size = '8px';
  const dots = new Array(10).fill(null);

  const animation = keyframes({
    '0%': {
      opacity: 1,
    },
    '20%': {
      opacity: 0,
    },
    '100%': {
      opacity: 1,
    },
  });

  return (
    <Grid
      sx={{
        gap: 1,
        p: 5,
        textAlign: 'center',
        justifyContent: 'center',
      }}
    >
      Loading
      <Grid
        sx={{
          gridAutoFlow: 'column',
          gap: 2,
        }}
      >
        {dots.map((dot, index) => (
          <Box
            key={index}
            sx={{
              animationDelay: `${index / 10}s`,
              animationDuration: '1.2s',
              animationTimingFunction: 'linear',
              animationIterationCount: 'infinite',
              animationName: animation.toString(),
              backgroundColor: 'primary',
              borderRadius: `${size}`,
              height: `${size}`,
              width: `${size}`,
              opacity: 0,
            }}
          />
        ))}
      </Grid>
    </Grid>
  );
};

functional values

I’ve talked a lot about how Theme UI maps CSS properties to specific theme objects, e.g color and background-color automatically map to colors… but if you need to access a value from your theme and map it to a different CSS property you can do so by using functional values

The idea here is you pass the theme object on via an inline function and by using template literals you can construct any CSS value you need.

Src 👇

<Box
  sx={{
    boxShadow: (theme) => `0 0 7px 3px ${theme.colors.secondary}`,
    backgroundColor: 'surface',
    color: 'secondary',
    p: 3,
  }}
>
  I'm a Box
</Box>

I’m sure i’ve implemented a number of other CSS methods using Theme UI on various projects but I can’t think of any more right now. I’ll endeavour to update this post as and when any new ones come to mind.

That just about wraps up this series on Theme UI, if you have any questions please feel free to find me on Twitter