Installation

How to install System Props and get up and running.

Install System Props

Install System Props from your terminal via npm or yarn. If you don't already have a CSS-in-JS library like Styled Components installed, you'll need one, too.

# With npm
npm install system-props styled-components

# With yarn
yarn add system-props styled-components
# With npm
npm install system-props styled-components

# With yarn
yarn add system-props styled-components
Copy

Create Your System

System Props begins with creating a system which dictates how the rest of the System Props function.

import { createSystem } from 'system-props';
import { createSystem } from 'system-props';
Copy

This function receives a configuration object:

• strict: Optionally constrain system prop values to values from the theme object.
• pseudoSelectors: Define a map of component prop (key) to a pseudo selector (value)

// Shown are the default values
const system = createSystem({
  strict: false,
  pseudoSelectors: {
    _hover: '&:hover',
    _focus: '&:focus',
    _hoverAndFocus: '&:hover, &:focus',
    _disabled:
      '[disabled], [disabled]:hover, [disabled]:focus, [aria-disabled], [aria-disabled]:hover, [aria-disabled]:focus',
    _readOnly: '[readOnly]',
    _first: '&:first-child',
    _last: '&:last-child',
    _odd: '&:nth-of-type(odd)',
    _even: '&:nth-of-type(even)',
  },
});
// Shown are the default values
const system = createSystem({
  strict: false,
  pseudoSelectors: {
    _hover: '&:hover',
    _focus: '&:focus',
    _hoverAndFocus: '&:hover, &:focus',
    _disabled:
      '[disabled], [disabled]:hover, [disabled]:focus, [aria-disabled], [aria-disabled]:hover, [aria-disabled]:focus',
    _readOnly: '[readOnly]',
    _first: '&:first-child',
    _last: '&:last-child',
    _odd: '&:nth-of-type(odd)',
    _even: '&:nth-of-type(even)',
  },
});
Copy

Create Your First Component

import { createSystem, color } from 'system-props';
import styled from 'styled-components';

const system = createSystem();

const Box = styled.div(system(color));

export default Box;
import { createSystem, color } from 'system-props';
import styled from 'styled-components';

const system = createSystem();

const Box = styled.div(system(color));

export default Box;
Copy

Now, this component will have two style props available: color to set foreground color, and bg to set background color. (You can also use backgroundColor if you're adverse to terse naming conventions.)

render(
  <Box color="#fff" bg="tomato">
    Tomato
  </Box>
);
render(
  <Box color="#fff" bg="tomato">
    Tomato
  </Box>
);
Copy

Theming

So far, this component can be styled with any valid CSS color. The real advantage of System Props is its tight integration with a theme object to create more consistent UIs. (Design systems!)

Most CSS-in-JS libraries include a ThemeProvider to provide values through React context. Import the styled-components ThemeProvider in the root of your application and pass the theme to the theme prop.

import React from 'react';
import { ThemeProvider } from 'styled-components';

const theme = {
  colors: {
    primary: {
      base: '#3578e5',
    },
    white: '#fff',
  },
};

const App = (props) => (
  <ThemeProvider theme={theme}>{/* application elements */}</ThemeProvider>
);

export default App;
import React from 'react';
import { ThemeProvider } from 'styled-components';

const theme = {
  colors: {
    primary: {
      base: '#3578e5',
    },
    white: '#fff',
  },
};

const App = (props) => (
  <ThemeProvider theme={theme}>{/* application elements */}</ThemeProvider>
);

export default App;
Copy

With the ThemeProvider added, the Box component now has access to the colors defined in the theme object.

render(
  <Box color="white" bg="primary.base">
    Blue Box
  </Box>
);
render(
  <Box color="white" bg="primary.base">
    Blue Box
  </Box>
);
Copy

System Props will attempt to find a value based on keys in the theme and fallback to the raw value if it's not defined in the theme (unless strict was enabled in the createSystem configuration.

render(
  <Box color="white" bg="tomato">
    Tomato Box
  </Box>
);
render(
  <Box color="white" bg="tomato">
    Tomato Box
  </Box>
);
Copy

To make the Box component a little more useful, add a few more System Props functions to handle layout styles.

import styled from 'styled-components';
import { createSystem, space, layout, color } from 'system-props';

const system = createSystem();

const Box = styled.div`
  ${system({ ...space, ...layout, ...color })}
`;

export default Box;
import styled from 'styled-components';
import { createSystem, space, layout, color } from 'system-props';

const system = createSystem();

const Box = styled.div`
  ${system({ ...space, ...layout, ...color })}
`;

export default Box;
Copy

If you prefer using the plain object syntax, you can pass System Props functions in as arguments.

// example using object syntax
const Box = styled('div')(
  {
    boxSizing: 'border-box',
  },
  system({
    ...color,
    ...layout,
    ...space,
  })
);
// example using object syntax
const Box = styled('div')(
  {
    boxSizing: 'border-box',
  },
  system({
    ...color,
    ...layout,
    ...space,
  })
);
Copy