# polished: Sass-style helpers for CSS-in-JS

> polished is a small JavaScript library of Sass-like colour, spacing and mixin helpers that return plain style objects, so it works inside styled-components, emotion, JSS or inline styles. The trade-off is that it is a function library, not a styling engine, and its docs leave a few integration details unstated.

**styled-components/polished** — A lightweight toolset for writing styles in JavaScript ✨

- Repository: https://github.com/styled-components/polished
- Website: https://polished.js.org/
- Stars: 7,665 · Forks: 216
- Language: JavaScript
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/styled-components-polished

## The gap polished fills between Sass and style objects

Writing styles as JavaScript objects removes the preprocessor, and with it a set of conveniences people rely on daily: lightening a brand colour by ten percent, desaturating it for a hover state, emitting a clearfix, generating keyframes. Without a helper layer you either hardcode the resulting values or reimplement the maths. polished supplies that layer. The README frames the audience directly: developers who "want to write styles in JavaScript, but also want Sass-style helper functions and mixins", and who need "a consistent color palette throughout your app".

The library is deliberately not tied to one styling engine. The README lists styled-components, emotion, jss, aphrodite, radium and plain inline styles, and states the only requirement is that you accept styles as JS objects. That is the design constraint that keeps it small: a function like lighten takes a colour and an amount and returns a string, so it has no opinion about how the string reaches the DOM.

## Curried colour functions and why the import style matters

The mechanism is functional composition. The README states that polished is written in a functional style and that "all color functions are curried", which allows them to be combined into your own helpers using any compose function. The documented example composes lighten(0.1) with desaturate(0.1) to build a tone() helper. Because each colour function takes one argument at a time, partial application gives you a reusable transform rather than a one-off value.

The second mechanism is module shape. polished ships as a set of stand-alone modules, and the README is explicit that you should not import the whole library. Importing named functions lets webpack and Rollup tree-shake the rest, and package.json sets "sideEffects": false to support that. The package also exposes "main": "dist/polished.cjs.js" and "module": "dist/polished.esm.js", so bundlers pick the ESM build and the CJS build serves Node consumers. Types come from "types": "lib/index.d.ts".

One consequence worth stating plainly: the README shows the discouraged forms with a strikethrough rather than explaining the cost. A wildcard import defeats tree shaking, and the package is described as lightweight, so the penalty is proportional to how much of the surface you pull in.

## Installing polished and using it in a real component

Installation is a single npm or yarn command, as the README gives it:

```bash
npm install --save polished
# or if you're using yarn
yarn add polished
```

There is no CLI, no config file and no build step of your own. The next step is importing the specific helpers you need. The README's own example imports clearFix and animation by name:

```js
import { clearFix, animation } from 'polished'
```

For TypeScript projects, the README states you must set moduleResolution to node in tsconfig.json before the bundled definitions resolve correctly:

```json
{
  "compilerOptions": {
    "moduleResolution": "node"
  }
}
```

If you use Flow and hit errors originating inside the package, the README documents an ignore entry for .flowconfig:

```bash
[ignore]
.*/node_modules/polished/.*
```

A first real use is the composition pattern from the README. Import a compose function of your choice, then build a project-specific helper:

```js
import { compose } from 'ramda' // Replace with any compose() function of your choice
import { lighten, desaturate } from 'polished'

// Create tone() helper
const tone = compose(lighten(0.1), desaturate(0.1))
```

After this, tone is a function you call with a colour string wherever a colour is expected. What you should see depends on your styling library: with styled-components or emotion the returned string lands in the generated CSS, with inline styles it lands in the style attribute. The README does not show the rendered output of the composed helper, so verify the values your own palette produces.

## Where polished stops: runtime cost and missing guarantees

polished is a function library, so every helper call that is not compiled away runs at render time. The README acknowledges this: it offers babel-plugin-polished as an optional way to "compile the static function calls out and remove the (already tiny) runtime performance impact". The parenthetical is the project's own characterisation; the README gives no measurement, and none is offered here. The practical point is that the plugin is opt-in, and static calls are only those whose arguments are known at build time.

There is also a documentation boundary. The README points to polished.js.org/docs for the full reference and does not enumerate the exported helpers, so the list of available functions is not something you can confirm from the repository front page. The README likewise does not document rollback or a migration path between major versions, and the release history shows a long gap between v4.2.2 in April 2022 and v4.3.1 in February 2024, which is worth knowing if you depend on prompt fixes. The last push to the repository was on 2026-03-26.

Browser support is stated as "All Evergreen Browsers + IE11", with the build targets given as >0.5%, not dead, ie >= 11, not op_mini all. If your support matrix has moved past IE11, that target is dead weight you cannot remove yourself.

## polished against Sass and against a full CSS-in-JS runtime

The most direct alternative is keeping Sass. Sass gives you the same colour functions and mixins, but it runs as a build step over .scss files, so the values are computed once at compile time and shipped as CSS. polished computes in JavaScript, which means a colour can depend on a runtime value such as a theme object or a prop. That is the difference that matters: Sass cannot read your React props, and polished cannot give you nesting, variables or @extend.

Against a full CSS-in-JS runtime such as styled-components or emotion, the comparison is not competitive at all. Those libraries generate and inject styles and manage class names; polished only produces values and object fragments that such a library consumes. The README positions polished as compatible with them rather than as an alternative. If you have not chosen a styling engine yet, polished is not the decision you are making.

A third option is writing the helpers yourself. Lightening a hex colour is a short function, and a team with a fixed palette may prefer twenty lines of local code to a dependency. polished earns its place when you want the breadth of the helper set, including mixins like clearFix and animation, without maintaining it.

## Licence, maintenance and what an upgrade actually costs

polished is MIT licensed, and package.json declares "license": "MIT" with LICENSE.md at the repository root. MIT permits commercial use and modification provided the copyright notice and permission notice are retained; that is a statement about the licence text, not legal advice, and teams with unusual distribution requirements should read LICENSE.md themselves.

Upgrade cost is mostly the cost of the colour maths and the API surface you use. There is no runtime to migrate and no config schema to rewrite, so a version bump is usually a dependency change plus a test run. The visible risk is behavioural: a helper that returns a slightly different colour string will change output without failing a type check. The README does not document a changelog or a deprecation policy, so pinning a version and reading the release notes for v4.3.1 before upgrading is the cautious route. The optional babel-plugin-polished is a separate package with its own release cadence, so treat it as a second dependency to track.

## Conclusion

Adopt polished if you already write styles as JavaScript objects and miss Sass colour maths, clearFix or animation helpers, and you are willing to import each function by name so tree shaking can drop the rest. Do not adopt it if you want a styling runtime, a preprocessor or a design-token system; polished returns objects and nothing more, and the README does not describe a component API. Before committing, check that your tsconfig.json sets moduleResolution to node, since the README states that is required for the TypeScript definitions, and confirm on polished.js.org/docs which helpers your version exports.

## FAQ

### How do I install polished in a JavaScript project?

The README gives npm install --save polished, or yarn add polished if you use Yarn. There is no CLI or global install step.

### How do I use polished with styled-components or another CSS-in-JS library?

Import the individual helpers by name, for example import { clearFix, animation } from 'polished', and call them where a style value is expected. The README states polished is compatible with any library that accepts styles as JS objects.

### Why does the README say not to import all of polished?

The README states that importing the whole library prevents tree shaking in webpack and Rollup, so the unused helpers stay in your bundle. Importing named functions lets those bundlers drop the rest.

### Does polished work with TypeScript?

Yes. The README states polished ships TypeScript definitions, and that you need to set moduleResolution to node in tsconfig.json to use them.

### Can I remove the runtime cost of polished helper calls?

The README mentions babel-plugin-polished as an optional plugin that compiles static function calls out. It applies to calls whose arguments are known at build time.

## Sources

- [License: MIT](https://github.com/styled-components/polished/blob/main/LICENSE)
- [Project website](https://polished.js.org/)
- [README](https://github.com/styled-components/polished/blob/main/README.md)
- [Releases](https://github.com/styled-components/polished/releases)
- [styled-components/polished on GitHub](https://github.com/styled-components/polished)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/styled-components-polished