Theming

Introduction

@deity/falcon-ui ships with powerful ThemeProvider based theming capabilities. Every component has default theme built-in, providing a consistent and pleasing look and feel out of the box, yet giving possibility to customize it in every detail.

Default theme

Default theme is influenced by constraint-based design system principles, based on typographic scale and 8px grid. It specifies font sizes, colors, spacings as well as many other values needed for creating consistent, systematic design. You can see all theme default values specified in source code, or

When using ThemeProvider without specifying theme prop, default theme is being used.

xxxxxxxxxx

import { ThemeProvider, Button } from '@deity/falcon-ui';

​

const App = (

  <ThemeProvider>

    <Button>Hello!</Button>

  </ThemeProvider>

);

Additional resources

• Constructing design system
• 8px grid system

Customizing theme

All theme related customizations are done using createTheme function by providing necessary overrides and passing its output as theme prop to ThemeProvider. Example below shows how to override primary color and font family.

<ThemeProvider theme={customizedTheme}>

  <H1>Theme customization</H1>

  <FlexLayout mt="md" justifyContent="center">

    <Button>in action</Button>

  </FlexLayout>

</ThemeProvider>

xxxxxxxxxx

import { createTheme } from '@deity/falcon-ui';

​

const customizedTheme = createTheme({

  colors: {

    primary: '#A9CF38'

  },

  fonts: {

    sans: '"Comic Sans MS", "Comic Sans", cursive'

  }

});

You can play around with theme values via

and see generated code on Theme editor's Download tab.

In addition to ovderriding default theme values, there is an easy way to override each component theme, via components section as shown below:

<H2>Component level theme customization</H2>

<Button mt="md">Default theme</Button>

<ThemeProvider theme={customizedButtonTheme}>

  <Button mt="md">Custom button theme</Button>

</ThemeProvider>

xxxxxxxxxx

import { createTheme } from '@deity/falcon-ui';

​

const customizedButtonTheme = createTheme({

  components: {

    button: {

      height: 'xl',

      px: 'lg',

      bg: 'transparent',

      color: 'secondaryText',

      fontWeight: 'bold',

      border: 'bold',

      borderColor: 'primary',

      borderRadius: 'round'

    }

  }

});

Every component accepts all of the responsive, theme-based style props as well as css prop.

The easiest way to find component key to use in components object in theme object is to use Theme Editor's Component Locator. Just click on the icon on the right to activate it and hover over interesting component to display it's key to use in components object (for example Card component below).

Custom themed components

In addition to built-in components, there is an easy way to create custom components with default theme that also plugin-in into the general theming system. This can be accomplished by themed factory as in example below.

xxxxxxxxxx

import { themed } from '@deity/falcon-ui';

​

export const Card = themed({

  tag: 'div',

  defaultTheme: {

    card: {

      p: 'md',

      boxShadow: 'subtle',

      borderRadius: 'medium',

      bg: 'white',

      fontSize: 'lg',

      css: {

        textAlign: 'center'

      }

    }

  }

});

tag specifies html tag Element will be rendered as, which can be overriden via as prop as shown in example below. defaultTheme accepts object with single key that will be key used in theme components section to overrride default components styles.

<Card>Custom theme based card component</Card>

<Card as="article" mt="lg">

  Custom theme based card component rendered as an article

</Card>