Styled-bettertools NPM

styled-bettertools 💅

This project is a fork of styled-tools, which is no longer maintained. The main goal of this project is to keep the same API and add new features and improvements.

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

Install

npm:

npm i styled-bettertools

Yarn:

yarn add styled-bettertools

Usage

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

// If the component does not have Props interface, pass <object>
// to prevent the generic functions type from being incorrectly inferred
// or pass the Props interface as generic
const Button = styled.button<object>`
  color: ${prop<{ color: string }>("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 <
  object >
  `
  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

prop

Returns the value of props[path] or defaultValue

Parameters

path string
defaultValue any

Examples

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

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

deepProp

A utility function to retrieve a property value from a component's props that deeply resolves each property in the path.

Parameters

path string
defaultValue any

Examples

import styled from "styled-components";
import { deepProp } from "styled-bettertools"; // or "styled-bettertools/deep-prop"

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

function App() {
  return <Button color={{ primary: () => "blue" }} />;
}

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-bettertools";

const Button =
  styled.button <
  object >
  `
  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-bettertools";

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-bettertools";

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

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-bettertools";

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

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-bettertools";

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}`)};
`;

switchProp

Switches on a given prop. Returns the value or function for a given prop value. Third parameter is default value.

Parameters

needle Needle
cases (Object | PropsFn)
defaultCase any

Examples

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

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

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

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)