Styled Fleet

Building theming for styled components

English | Español

🎴 Demo

📦 Install

npm install styled-fleet

yarn add styled-fleet

🔨 Usage

Create a theme

import {createTheme} from 'styled-fleet';

const theme = createTheme({
  colors: {
    white: '#fff',
    black: '#000',
  },
  space: ["0rem", "0.5rem", "1rem", "1.5rem", "2rem", "2.5rem", "3rem"],
  font: {
    sizes: ['0.75rem', '0.875rem', '1rem', '1.25rem', '1.5rem', '1.75rem', '2rem', '2.5rem', '3rem'],
    family: ['sans-serif'],
    weights: {
      body: 400,
      heading: 700,
      bold: 700,
      light: 300,
      medium: 500,
      semibold: 500,
    }
  },
  modes: {
    light: {
      background: '$theme-colors-white',
      text: '$theme-colors-black',
    },
    dark: {
      background: '$theme-colors-black',
      text: '$theme-colors-white',
    },
  },
});

Create a styled component and access the theme with $theme-... , or if you prefer you can use the css notation with var(--theme-...)

import styled from 'styled-components';

export const Button = styled.button`
  display: inline-block;
  border: none;
  padding: $theme-space-2 $theme-space-4;
  margin: $theme-space-0;
  text-decoration: none;
  font-family: $theme-font-family-0;
  font-size: $theme-font-sizes-2;
  font-weight: $theme-font-weights-medium;
  cursor: pointer;
  text-align: center;
  transition: background 250ms ease-in-out, transform 150ms ease;
  color: $theme-text;
  background-color: var(--theme-background);
`;

Add the theme to ThemeProvider and use the component

import * as React from 'react';
import {ThemeProvider} from 'styled-fleet';

export const App = () => {
  return (
    <ThemeProvider theme={theme} >
      <Button>
        Example Button
      </Button>
    </ThemeProvider>
  );
};

🔧 API

createTheme

Function that allows you to create a theme.

Parameters	Type	Description
theme (required)	DefaultTheme	Theming context object
options (optional)	ThemeOptions	Options object for theme processing

DefaultTheme

Object with custom key / value that will define the global css variables, the styles and modes keys are reserved to define global styles and theme modes respectively, for example.

{
  colors: ...,
  sizes: ...,
  fonts: ...,
  shadows: ...,
  ...
  styles: {
    body: {
      backgroundColor: '$theme-background',
      color: '$theme-text',
      ...
    },
    a: ...,
    h1: ...,
    h2: ...,
    code: ...,
    pre: ...,
    hr: ...,
    ...
  },
  modes: {
    light: {
      background: '$theme-colors-white',
      text: '$theme-colors-black',
      ...
    },
    dark: {
      background: '$theme-colors-black',
      text: '$theme-colors-white',
      ...
    },
    ...
  },
}

ThemeOptions

Object with the following keys

Key	Type	Description	Default	Example
prefix (optional)	string	Prefix to use in css variables	'theme'	$theme-colors-red
useLocalStorage (optional)	boolean	Enable or disable local storage to store the set theme mode	true	useLocalStorage: true
defaultMode (optional)	string	Set the default theme mode	'default'	defaultMode: 'light'
scope (optional)	string or styled-component	Allows you to set the scope of global CSS variables	':root'	scope: 'body' scope: Sider
functions (optional)	Function[]	An array of custom functions that can be accessed by @<function name>(...arguments), This allows you to extend and add features to your css styles	[]	functions: [cssVar, ...]

Note:

• All custom functions will be processed with string parameters, so the function will have to ensure the data type conversion and error handling in case of any wrong parameter.
• You can use external package functions like polished or others.
• The functions have to return a correct value for the css styles, it can be a string or a number.
• Sometimes you have to set a name to the function so that styled-fleet can access it, example

const rgba = (red, green, blue, alpha) => { ... };

Object.defineProperty(rgba, 'name', { value: 'rgba' });

Example:

import styled from 'styled-components';
import {createTheme} from 'styled-fleet';
import {rgba, darken, lighten} from 'polished';

const theme = { ... };

const options = {
  prefix: 'my-prefix',
  useLocalStorage: false,
  defaultMode: 'light',
  scope: ':root',
  functions: [rgba, darken, lighten],
};

export default createTheme(theme, options);

//  To use it in a component
const MyComponent = styled.div`
  padding: $my-prefix-space-2;
  background-color: @rgba(#000, 0.5);
  color: @darken(0.2, #fff);
  border: 1px solid @lighten(.2, #000);
`;

ThemeProvider

Provider component that provides a theme for all React components under itself.

Props	Description	value
theme (required)	Required prop for global app theming	Object returned by createTheme

Example:

import * as React from 'react';
import {createTheme, ThemeProvider} from 'styled-fleet';

const theme = createTheme({...}, {...});

const App = () => {
  return (
    <ThemeProvider theme={theme}>
      ...
    </ThemeProvider>
  )
};

useMode

Hook that allows accessing or setting the current theme mode in the context of ThemeProvider.

• Does not receive input parameters.
• Returns a pair of values that can be destructuring into
  • mode, string containing current mode theme.
  • setMode, function that allows setting the theme mode, receives as the only parameter a string that represents the theme to be used.

Example:

import * as React from 'react';
import styled from 'styled-components';
import { useMode } from 'styled-fleet'

import { Button } from './Button';
import { MoonIcon } from './MoonIcon';
import { SunIcon } from './SunIcon';

const IconButton = styled(Button)`
  background-color: transparent;
  border: $theme-borders-0;
  cursor: pointer;
  padding: $theme-space-0;
  color: $theme-color;
  align-items: center;
  display: flex;
  gap: $theme-space-1;
  outline: none;
`;

export const ButtonThemeMode = () => {
  const {mode, setMode} = useMode();

  return (
    <IconButton onClick = {() => setMode(mode === 'light' ? 'dark' : 'light') } >
      { mode === 'light'
        ? ( <MoonIcon /> )
        : ( <SunIcon /> ) }
      <h4> Switch to { mode === 'light' ? 'dark' : 'light' } mode </h4>
    </IconButton>
  );
};

⚠️ Limitations

• Currently it is not possible to access the value of css variables in the first rendering of the application, so functions like polished cssVar that allows obtaining global css variables, will fail if a default value is not specified. This behavior also occurs with styled-components when setting css variables in the root and trying to get their value.
• When using functions to calculate a value of a css property, it is possible that if you are using css variables and change the theme mode you will not get the expected result, this is because in the first rendering when processing the css styles, the variable css has been changed to the new value calculated by the function, unless the function returns another css variable as a result depending on the theme mode

License

Licensed under the MIT License.

See LICENSE for more information.