Theming

Theming is a core concept in Mineral UI. Themes provide a consistent look and feel across pages with varied functionality. Mineral UI makes it simple to implement and maintain theming across your app.

Common Scenarios #

Theme your entire app #

Wrap your app in a ThemeProvider in order for styles to be properly applied. The ThemeProvider provides the theme to the tree of Mineral UI components, and any other Emotion components contained within.

import React from 'react';
import { render } from 'react-dom';
import Button from 'mineral-ui/Button';
import { ThemeProvider } from 'mineral-ui/themes';

function App() {
  return (
    <ThemeProvider>
      <Button>
        Hello World
      </Button>
    </ThemeProvider>
  );
}

render(<App />, document.getElementById('app'));

Theme a portion of your app #

ThemeProviders may be nested in order to apply a custom theme to a portion of your app. Nested ThemeProviders shallowly merge their theme with the parent theme. The theme itself is a simple shallow object of variables that are shared across components.
See the default mineralTheme below for an example.

<ThemeProvider>
  <ThemeProvider theme={{ color_themePrimary: 'darkgray' }}>
    <nav>Navigation<nav>
  </ThemeProvider>
  <main>The main part of your app</main>
</ThemeProvider>

Theme a component #

Each component has a set of component-level theme variables that may be overridden to adjust styles on a per component basis. These are documented on the individual component pages, e.g. Button theme variables.

To theme a component, use themed as shown below. It is effectively the same as wrapping your component with a ThemeProvider.

import { themed } from 'mineral-ui/themes';

const MyButton = themed(Button)({
  Button_backgroundColor: 'tomato'
});

Create your own theme #

Use createTheme in order to create a custom theme. Once created, this theme can be applied using a ThemeProvider.

Use a custom color palette #

Each theme variable with a color value derives that value from a color ramp in Mineral UI's palette. Those colors can be derived from a different palette color (e.g. "danger" variables use 'bronze' instead of 'red', below) or a custom color ramp can be used (e.g. myAppColor is used for "theme" variables, below).

import React from 'react';
import { render } from 'react-dom';
import Button from 'mineral-ui/Button';
import { createTheme, ThemeProvider } from 'mineral-ui/themes';

const myAppColor = {
  [10]: '#faf0f4',
  [20]: '#fad4e4',
  [30]: '#fab4d1',
  [40]: '#f78bb8',
  [50]: '#ed5393',
  [60]: '#d6246e',
  [70]: '#b01355',
  [80]: '#8a1244',
  [90]: '#611535',
  [100]: '#421527'
}

const myTheme = createTheme({
  colors: {
    theme: myAppColor,
    danger: 'bronze',
    warning: 'dusk',
    success: 'teal'
  }
});

function App() {
  return (
    <ThemeProvider theme={myTheme}>
      <Button>
        Hello World
      </Button>
    </ThemeProvider>
  );
}

render(<App />, document.getElementById('app'));

API #

<ThemeProvider theme /> #

This component takes a theme property and provides it to the tree of components contained within. When nested, child themes will be shallowly merged with the parent theme.

See the previous examples and the ThemeProvider page for more details.

themed(component)(theme) #

This function is useful when you need to override component-level theme variables. It is effectively the same as wrapping a ThemeProvider around a single component.

Parameters

• component: A React component
• theme: A shallow object of theme variables or a function that accepts props and returns a shallow object of theme variables

Returns

• The original React component wrapped in a ThemeProvider with the merged theme provided.

Example

import { themed } from 'mineral-ui/themes';

// The \`theme\` prop is the theme available from the nearest ThemeProvider in
// the component tree
const MyButton = themed(Button)(({ theme }) => ({
  Button_backgroundColor: theme.color_theme_10
}));

createTheme(options) #

This function is useful when you want to create a new theme that uses a different color scheme or otherwise overrides default values.

Parameters

• options: Optional. An object with the following shape. All properties are optional.

Types

• Color: String matching a color ramp name in the Mineral UI palette

• Ramp: Object matching this shape:

  const myRamp = {
    [10]: '<color>',
    [20]: '<color>',
    [30]: '<color>',
    [40]: '<color>',
    [50]: '<color>',
    [60]: '<color>',
    [70]: '<color>',
    [80]: '<color>',
    [90]: '<color>',
    [100]: '<color>',
    inflection: 70
  };

  Inflection Point

  Note the optional inflection property. Mineral UI's color ramps are designed to provide an accessible level of contrast, which they accomplish through two constraints:

  1. Each ramp contains 10 color values, each spaced roughly evenly from one another.
  2. Each ramp's inflection point (where text color changes from black to white to meet accessible contrast ratio standards) occurs at the60 value.

  Your custom ramp must meet the first constraint of 10 values. But the inflection point, while advised to be 60, may be different. You may define it with the inflection property to ensure adequate contrast.

Returns

• A new theme object

Example

import { createTheme } from 'mineral-ui/themes';

const myTheme = createTheme({
  colors: { theme: 'dusk' },
  overrides: { fontFamily: 'Comic Sans MS' }
});

withTheme(component) #

A higher order component (HOC) that enables theme access inside any component.

Parameters

• component: A React component

Returns

• The original React component with theme provided as a prop.

Example

import { withTheme } from 'emotion-theming';

const Direction = withTheme(({ theme }) => {
  return <span>{theme.direction}</span>;
});

Theme Structure #

Mineral UI themes are shallow objects of variables that are shared across components. The values in the table below are from the default mineralTheme. Note the naming convention: [target]_[property]_[variation]_[state].