styled-tools

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #typescript #llm #golang #rust #linux #windows #awesome #cli #kubernetes #awesome-list #open-source

(★ 799)

Useful interpolated functions for CSS-in-JS

File Explorer

Download Latest Version (.zip)

- index.js
- ifNotProp.js
- ifProp.js
- index.js
- index.js.flow
- palette.js
- prop.js
- switchProp.js
- theme.js
- withProp.js
- ifNotProp.test.js
- ifProp.test.js
- palette.test.js
- prop.test.js
- switchProp.test.js
- theme.test.js
- withProp.test.js
- index.d.ts
- tests.ts
.editorconfig
.eslintignore
.eslintrc
.flowconfig
.gitignore
.travis.yml
babel.config.js
CHANGELOG.md
documentation.yml
index.js
LICENSE
package.json
README.md
tsconfig.json
yarn.lock

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# styled-tools 💅

[![NPM version](https://img.shields.io/npm/v/styled-tools.svg?style=flat-square)](https://npmjs.org/package/styled-tools)
[![NPM downloads](https://img.shields.io/npm/dm/styled-tools.svg?style=flat-square)](https://npmjs.org/package/styled-tools)
[![Dependencies](https://img.shields.io/david/diegohaz/styled-tools.svg?style=flat-square)](https://david-dm.org/diegohaz/styled-tools)
[![Build Status](https://img.shields.io/travis/diegohaz/styled-tools/master.svg?style=flat-square)](https://travis-ci.org/diegohaz/styled-tools) [![Coverage Status](https://img.shields.io/codecov/c/github/diegohaz/styled-tools/master.svg?style=flat-square)](https://codecov.io/gh/diegohaz/styled-tools/branch/master)

Useful interpolated functions for [styled-components](https://github.com/styled-components/styled-components) 💅, [emotion](https://github.com/emotion-js/emotion) 👩‍🎤, [JSS](https://github.com/cssinjs/jss) and other CSS-in-JS libraries.

## Install

npm:

npm i styled-tools

Yarn:

yarn add styled-tools

## Usage

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

// 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:

```jsx
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](#prop)
    -   [Parameters](#parameters)
    -   [Examples](#examples)
-   [theme](#theme)
    -   [Parameters](#parameters-1)
    -   [Examples](#examples-1)
-   [palette](#palette)
    -   [Parameters](#parameters-2)
    -   [Examples](#examples-2)
-   [ifProp](#ifprop)
    -   [Parameters](#parameters-3)
    -   [Examples](#examples-3)
-   [ifNotProp](#ifnotprop)
    -   [Parameters](#parameters-4)
    -   [Examples](#examples-4)
-   [withProp](#withprop)
    -   [Parameters](#parameters-5)
    -   [Examples](#examples-5)
-   [switchProp](#switchprop)
    -   [Parameters](#parameters-6)
    -   [Examples](#examples-6)
-   [Types](#types)
    -   [Needle](#needle)

### prop

Returns the value of `props[path]` or `defaultValue`

#### Parameters

-   `path` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `defaultValue` **any**

#### Examples

```javascript
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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `defaultValue` **any**

#### Examples

```javascript
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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))** 
-   `toneOrDefaultValue` **any** 
-   `defaultValue` **any**

#### Examples

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

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

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

### ifProp

Returns `pass` if prop is truthy. Otherwise returns `fail`

#### Parameters

-   `test` **([Needle](#needle) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[Needle](#needle)> | [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))** 
-   `pass` **any**  (optional, default `""`)
-   `fail` **any**  (optional, default `""`)

#### Examples

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

Returns **PropsFn**

### ifNotProp

Returns `pass` if prop is falsy. Otherwise returns `fail`

#### Parameters

-   `test` **([Needle](#needle) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[Needle](#needle)> | [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))** 
-   `pass` **any** 
-   `fail` **any**

#### Examples

```javascript
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](#needle) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[Needle](#needle)>)** 
-   `fn` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)**

#### Examples

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

Returns **PropsFn**

### switchProp

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

#### Parameters

-   `needle` **[Needle](#needle)** 
-   `cases` **([Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) | PropsFn)** 
-   `defaultCase` **any**

#### Examples

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

<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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function))

## License

styled-tools

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

styled-tools

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

Download README