styled-tools

What is styled-tools?

The styled-tools npm package provides utility functions for use with styled-components, allowing for more dynamic and reusable styles in your React applications.

What are styled-tools's main functionalities?

theme

The `theme` function allows you to access theme properties defined in your styled-components theme object. This makes it easy to apply consistent styles across your application.

const Button = styled.button`
  color: ${theme('colors.primary')};
`;

ifProp

The `ifProp` function allows you to conditionally apply styles based on the presence of a prop. This is useful for creating dynamic styles that change based on component props.

const Button = styled.button`
  background: ${ifProp('primary', 'blue', 'gray')};
`;

prop

The `prop` function allows you to use component props to set CSS properties. This makes it easy to create highly customizable components.

const Box = styled.div`
  padding: ${prop('padding', '10px')};
`;

switchProp

The `switchProp` function allows you to switch between different styles based on the value of a prop. This is useful for creating components with multiple variants.

const Button = styled.button`
  background: ${switchProp('size', {
    small: '10px',
    medium: '20px',
    large: '30px'
  })};
`;

Other packages similar to styled-tools

polished

Polished is a lightweight toolset for writing styles in JavaScript. It provides a variety of utility functions for color manipulation, math, and other CSS-related tasks. Compared to styled-tools, polished offers a broader range of utilities but does not focus specifically on styled-components.

styled-system

Styled-system is a collection of utility functions for building design systems with React. It allows you to style components based on a theme and provides responsive style props. Styled-system is more focused on creating consistent design systems, whereas styled-tools provides more general utility functions for styled-components.

emotion

Emotion is a library designed for writing CSS styles with JavaScript. It offers a similar API to styled-components and includes utility functions for theming and dynamic styling. Emotion provides a more comprehensive solution for styling in React, including both styled-components and CSS-in-JS utilities.

README

styled-tools 💅

Useful interpolated functions for styled-components 💅, emotion 👩‍🎤, JSS and other CSS-in-JS libraries.

Install

$ npm install --save styled-tools

Usage

import styled, { css } from "styled-components";
import { prop, ifProp, switchProp } from "styled-tools";

const Button = styled.button`
  color: ${prop("color", "red")};
  font-size: ${ifProp({ size: "large" }, "20px", "14px")};
  background-color: ${switchProp("theme", {
    dark: "blue", 
    darker: "mediumblue", 
    darkest: "darkblue" 
  })};
`;

// renders with color: blue
<Button color="blue" />

// renders with color: red
<Button />

// renders with font-size: 20px
<Button size="large" />

// renders with background-color: mediumblue
<Button theme="darker" />

A more complex example:

const Button = styled.button`
  color: ${prop("theme.colors.white", "#fff")};
  font-size: ${ifProp({ size: "large" }, prop("theme.sizes.lg", "20px"), prop("theme.sizes.md", "14px"))};
  background-color: ${prop("theme.colors.black", "#000")};
  
  ${switchProp("kind", {
    dark: css`
      background-color: ${prop("theme.colors.blue", "blue")};
      border: 1px solid ${prop("theme.colors.blue", "blue")};
    `,
    darker: css`
      background-color: ${prop("theme.colors.mediumblue", "mediumblue")};
      border: 1px solid ${prop("theme.colors.mediumblue", "mediumblue")};
    `,
    darkest: css`
      background-color: ${prop("theme.colors.darkblue", "darkblue")};
      border: 1px solid ${prop("theme.colors.darkblue", "darkblue")};
    `
  })}
  
  ${ifProp("disabled", css`
    background-color: ${prop("theme.colors.gray", "#999")};
    border-color: ${prop("theme.colors.gray", "#999")};
    pointer-events: none;
  `)}
`;

API

Table of Contents

• prop
  • Parameters
  • Examples
• theme
  • Parameters
  • Examples
• palette
  • Parameters
  • Examples
• ifProp
  • Parameters
  • Examples
• ifNotProp
  • Parameters
  • Examples
• withProp
  • Parameters
  • Examples
• switchProp
  • Parameters
  • Examples
• Types
  • Needle

prop

Returns the value of props[path] or defaultValue

Parameters

• path string
• defaultValue any

Examples

import styled from "styled-components";
import { prop } from "styled-tools";

const Button = styled.button`
  color: ${prop("color", "red")};
`;

Returns PropsFn

theme

Same as prop, except that it returns props.theme[path] instead of props[path].

Parameters

• path string
• defaultValue any

Examples

import styled from "styled-components";
import { theme } from "styled-tools";

const Button = styled.button`
 color: ${theme("button.color", "red")};
`;

palette

Returns props.theme.palette[key || props.palette][tone || props.tone || 0] or defaultValue.

Parameters

• keyOrTone (string | number)
• toneOrDefaultValue any
• defaultValue any

Examples

import styled, { ThemeProvider } from "styled-components";
import { palette } from "styled-tools";

const theme = {
  palette: {
    primary: ['#1976d2', '#2196f3', '#71bcf7', '#c2e2fb'],
    secondary: ['#c2185b', '#e91e63', '#f06292', '#f8bbd0']
  }
};

const Button = styled.button`
  color: ${palette(1)};                    // props.theme.palette[props.palette][1]
  color: ${palette("primary", 1)};         // props.theme.palette.primary[1]
  color: ${palette("primary")};            // props.theme.palette.primary[props.tone || 0]
  color: ${palette("primary", -1)};        // props.theme.palette.primary[3]
  color: ${palette("primary", 10)};        // props.theme.palette.primary[3]
  color: ${palette("primary", -10)};       // props.theme.palette.primary[0]
  color: ${palette("primary", 0, "red")};  // props.theme.palette.primary[0] || red
`;

<ThemeProvider theme={theme}>
  <Button palette="secondary" />
</ThemeProvider>

ifProp

Returns pass if prop is truthy. Otherwise returns fail

Parameters

• test (Needle | Array<Needle> | Object)
• pass any (optional, default "")
• fail any (optional, default "")

Examples

import styled from "styled-components";
import { ifProp, palette } from "styled-tools";

const Button = styled.button`
  background-color: ${ifProp("transparent", "transparent", palette(0))};
  color: ${ifProp(["transparent", "accent"], palette("secondary"))};
  font-size: ${ifProp({ size: "large" }, "20px", ifProp({ size: "medium" }, "16px", "12px"))};
`;

Returns PropsFn

ifNotProp

Returns pass if prop is falsy. Otherwise returns fail

Parameters

• test (Needle | Array<Needle> | Object)
• pass any
• fail any

Examples

import styled from "styled-components";
import { ifNotProp } from "styled-tools";

const Button = styled.button`
  font-size: ${ifNotProp("large", "20px", "30px")};
`;

Returns PropsFn

withProp

Calls a function passing properties values as arguments.

Parameters

• needle (Needle | Array<Needle>)
• fn Function

Examples

// example with polished
import styled from "styled-components";
import { darken } from "polished";
import { withProp, prop } from "styled-tools";

const Button = styled.button`
  border-color: ${withProp(prop("theme.primaryColor", "blue"), darken(0.5))};
  font-size: ${withProp("theme.size", size => `${size + 1}px`)};
  background: ${withProp(["foo", "bar"], (foo, bar) => `${foo}${bar}`)};
`;

Returns PropsFn

switchProp

Switches on a given prop. Returns the value or function for a given prop value.

Parameters

• needle Needle
• cases Object
• defaultCase any

Examples

import styled, { css } from "styled-components";
import { switchProp, prop } from "styled-tools";

const Button = styled.button`
  font-size: ${switchProp(prop("size", "medium"), {
    small: prop("theme.sizes.sm", "12px"),
    medium: prop("theme.sizes.md", "16px"),
    large: prop("theme.sizes.lg", "20px")
  }};
  ${switchProp("theme.kind", {
    light: css`
      color: LightBlue;
    `,
    dark: css`
      color: DarkBlue;
    `
  })}
`;

<Button size="large" theme={{ kind: "light" }} />

Returns PropsFn

Types

Needle

A Needle is used to map the props to a value. This can either be done with a path string "theme.size.sm" or with a function (props) => props.theme.size.sm (these two examples are equivalent).

All of styled-tools can be used as Needles making it possible to do composition between functions. ie ifProp(theme("dark"), "black", "white")

Type: (string | Function)

License

MIT © Diego Haz

Changelog

1.5.2 (2018-10-15)

Bug Fixes

• switchProp: Fix boolean values (4c09e1b)

<a name="1.5.1"></a>