Documentation

The motivation behind composable-styled-components is to provide a set of reusable functions that abstract some of the boilerplate code needed to create or extend a styled component. Partially utilizing recompose, this library uses higher-order components to build a styled-component with ease. The goal isn't to replace styled-components, but instead offer a DX-friendly way to compose them.

Installation

You can install composable-styled-components with either one of these package managers:

npm

npm install composable-styled-components styled-components --save

yarn (recommended)

yarn add composable-styled-components styled-components

NOTE

If you use a package manager like yarn that supports the "resolutions" package.json field, then it's highly recommended that you add an entry to it as well corresponding to the major version range. This helps avoid problems from multiple versions of styled-components being installed in your project.

{
  "resolutions": {
    "styled-components": "^5"
  }
}

Package Exports

This library exports the following default and named exports. To learn more about each and how to use them, visit the API section.

import compose, {
  css,
  compose,
  extend,
  nest,
  setDisplayName,
  withAttributes,
  withDefaultProps,
  withProps,
  withPropTypes,
  withStyles,
} from "composable-styled-components"

Getting Started

Just like styled-components, this package utilizes tagged template literals to style your components. For example, the code below creates two simple components, a wrapper and a title, and nests them together.

const Wrapper = compose.div(
  setDisplayName("Wrapper")
)`
  border: 3px solid palevioletred;
  border-radius: 4px;
  padding: 10px 20px;
`;

const Title = compose.div(
  setDisplayName("Title")
)`
  border: 3px solid #ff6c47;
  border-radius: 4px;
  color: #ff6c47;
  font-size: 20px;
  text-align: center;
`

const Headline = nest(Wrapper, Title);

render(
  <Headline>
    Hello!
  </Headline> 
);

Hello!

API

The table below covers the exports offered by composabled-styled-components. If you wish to see usage examples of the function(s), then click the link under the Property column.

Property	Usage	Description	Notes
compose (†)	fn.element(...fns)` ...styles `;	Composes an HTML element with composable functions and styles to create a styled-component.	The first argument to compose requires an HTML Element either declared as a property of compose: 'compose.div' or passed as a string to compose: 'compose("div")', the second argument is a list of composable functions separated by commas, and the third argument must be a template literal containing CSS properties. (†) Do not use within extend.
css (†)	fn` property: ${prop => 'string'}; property: ${prop => 'string'}; ...etc `;	Interpolates CSS properties that require passed in props.	Accepts a template literal with interpolated functions. The interopolated function must be a child of a CSS property and the function must return a string. (†) Only to be used within withStyles.
extend (†)	fn(...fns)(node);	Extends a node.	First argument accepts a list of functions separated by commas and the second argument requires a styled-component node. (†) Do not use within compose nor nest.
nest (†)	fn(...nodes);	Nests nodes from left to right.	Accepts nodes (React components) separated by commas. Each node wraps any successive nodes to the right. (†) Do not use within compose nor extend.
setDisplayName	fn('string');	Sets the display name of the node.	Attributes a display name to the component when viewed within the 'Components' tab. Requires the React Dev Tools browser extension.
withAttributes	fn({ ...props }); fn(props => ({ ...props }));	Creates or appends HTML attributes.	Accepts an object of properties or a function that return properties.
withDefaultProps	fn({ ...props });	Establishes default props.	Accepts an object of properties.
withProps	fn({ ...props }); fn(props => ({ ...props }));	Creates or appends additional props.	Accepts an object of properties or a function that return properties.
withPropTypes	fn({ ...props });	Establishes prop types.	Requires PropTypes package.
withStyles	fn({ ...props }); fn(props => ({ ...props })); fn(css` property: ${prop => 'string'}; property: ${prop => 'string'}; ...etc `);	Creates or appends styles.	Accepts an object of properties, a function that returns an object of properties, or the css helper function that interoplates CSS properties.

NOTE

Any functions with a dagger (†) have special use cases, please read the table above for more information.