polished generates TypeScript types out of its Flow files
A lightweight toolset for writing styles in JavaScript ✨
At a glance
- What is it?
- A lightweight toolset of Sass-style helpers for JavaScript, published by the styled-components authors, where every colour function is curried so you can compose your own. Two import forms are struck through in the readme, Flow and TypeScript type files are built in one chain, and TypeScript users have to set moduleResolution themselves.
- Who is it for?
- polished fits a codebase that moved from a pre-processor to styles in JavaScript and wants Sass-shaped helpers without adopting a build-time CSS language, or that wants the same colour helpers regardless of which CSS-in-JS library it uses. It does not fit if you need those helpers as a fluent object API.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Activity is slowing. The repository last received commits 7 months ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.
Star history
- styled-components/polished7,663 ★ · +1
| Repository | 2026-09-22 | 2026-11-13 |
|---|---|---|
| styled-components/polished | 7.7k | 7.7k |
1 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Two import forms are struck through on purpose
The usage section is unusually direct about how not to import the library. Modules are meant to be used as stand-alone imports:
import { clearFix, animation } from 'polished'Two alternatives appear with strikethrough formatting applied to them, which is the readme telling you they are wrong: importing the namespace, and importing a default. The consequence of getting this wrong is stated in the next sentence, because tree shaking in webpack and Rollup can only reduce your bundle when the imports are shaped correctly.
This is a small thing that people get wrong anyway, since a namespace import is the more natural habit. The readme describes the library as lightweight, so an import mistake here costs you the thing the package exists to provide.
Currying is the API, and compose is your extension point
The main stated difference from Sass is that polished is written in a functional style and all colour functions are curried. That is the design decision the whole library rests on, and the readme shows what it buys: you can compose the helpers into your own reusable functions using any compose implementation you prefer.
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))So a design system reduces to naming your own combinations. The example builds a tone() helper from a lighten and a desaturate step, and the import comment makes the point that the compose function is swappable.
The readme also explains why competitors were rejected: most other packages offering colour functions do so in an object-oriented style, often with a fluent API quite different from Sass-style helpers, which can be a barrier for people not deeply familiar with JavaScript.
TypeScript definitions are generated from the Flow files
There are two type systems here and one is derived from the other. Flow support is described as first class with zero configuration, and the build has a dedicated step for it, flow-copy-source, which copies the source into lib while excluding test files.
The TypeScript definitions are then generated from those Flow declaration files rather than hand written. build:typescript runs tsgen against lib with a glob for the .js.flow files, ignoring the underscore-prefixed ones, and the manifest points its types field at lib/index.d.ts. So the Flow files are the source of truth and the TypeScript output is a build artefact.
That arrangement has a practical consequence for consumers. There is one TypeScript requirement in the readme that is not optional: you have to set moduleResolution to node in your tsconfig.json for the definitions to resolve.
One build chain produces lib, dist, Flow, docs and types
The build script is a chain of five steps: build:lib, build:dist, build:flow, build:docs and build:typescript. Several have a pre-step that clears the output directory with shx, which is why there are prebuild:lib, prebuild:dist, prebuild:umd and prebuild:docs:site entries in the manifest.
The library itself is compiled by Babel with BABEL_ENV set to cjs into lib, and the bundles are produced by rollup from rollup.config.js into dist. The manifest points main at dist/polished.cjs.js and module at dist/polished.esm.js, so dist is the published entry and lib is an intermediate that also happens to hold the generated types.
The docs step is part of the same chain. It runs the documentation tool over the source with a custom theme from docs-theme, and the post step copies the CNAME file into the output and copies dist/polished.js into the docs assets, so the built bundle is what the documentation site loads.
The browser query keeps IE 11 and drops op_mini
Browser support is stated as all evergreen browsers plus IE 11, and then given as a browserslist query: as of v3.6.X the project supports greater than 0.5 percent usage, not dead, ie greater than or equal to 11, and not op_mini all, for all builds. A .browserlistrc file sits at the root of the repository, so that query is committed rather than assumed.
Keeping ie >= 11 while excluding op_mini all is a deliberate narrowing on both ends. The first keeps an old engine in scope, and the second drops a proxy browser family that browserslist would otherwise include by usage share.
The practical consequence is that transpilation targets are broad, and any syntax the library uses has to compile for that range.
sideEffects false is what makes named imports pay off
The manifest declares sideEffects false, which is the package-level promise that importing a module has no effect beyond what you use. Combined with the stand-alone import guidance, that is what allows a bundler to drop the functions you did not import.
Two adjacent notes complete the picture. Object spread properties appear throughout the documentation examples, and to use that syntax in your own project you have to add the transform-object-rest-spread plugin or the stage-3 preset to your Babel configuration, which is about your code rather than the library.
And there is an optional Babel plugin, babel-plugin-polished, whose stated purpose is to compile the static function calls out and remove the runtime performance impact of using the library. That is a fair description of the trade: a handful of tiny function calls per render, or none at all if you let the plugin fold them at build time.
v4.3.1 shipped in February 2024 after a two-year gap
The release history has an unusual shape. v4.2.1 and v4.2.2 landed two days apart on 4 and 6 April 2022. Then v4.3.1 on 1 February 2024. The manifest is at 4.3.1, matching the newest tag.
The last push to main is dated 26 March 2026, so the branch has moved for more than two years without a release. For a package of pure functions with a stable API that is not necessarily a problem, and there is no deprecation notice in the readme.
What the repository does show is conventional tooling rather than abandonment: a .husky directory for git hooks, .eslintrc with an .eslintignore, .prettierrc with a .prettierignore, a CODEOWNERS file, a code of conduct, and a .yarn directory with a .yarnrc and yarn.lock. Sponsorship runs through OpenCollective with backer and sponsor slots, and the copyright line names Brian Hough, Maximilian Stoiber and Nik Graf for 2016 to 2021.
Editorial conclusion
polished fits a codebase that moved from a pre-processor to styles in JavaScript and wants Sass-shaped helpers without adopting a build-time CSS language, or that wants the same colour helpers regardless of which CSS-in-JS library it uses. It does not fit if you need those helpers as a fluent object API. Before adopting, import it by named module rather than the package root, set moduleResolution to node in tsconfig.json if you are on TypeScript, and consider the Babel plugin if the runtime cost of the functions matters at your call volume.
Frequently asked questions
How do I use the polished style helpers?
Import the individual functions you need by name, for example import { clearFix, animation } from 'polished', and avoid importing the whole library. The readme strikes through the namespace and default import forms because they defeat tree shaking in webpack and Rollup.
Does polished only work with styled-components?
No. It is described as cross framework compatible, working with styled-components, emotion, jss, aphrodite, radium, glamor, glamorous or plain inline styles, on the basis that it is compatible with any library that accepts styles as JavaScript objects.
How do I keep the polished bundle small?
Import modules individually rather than the package root, since the package declares sideEffects false and named imports are what let webpack and Rollup drop unused functions. You can go further with babel-plugin-polished, which compiles static calls out and removes the runtime cost.
Do I need TypeScript configuration to use polished?
Yes, one setting. The readme states you need to set moduleResolution to node in your tsconfig.json for the TypeScript definitions to work. The definitions themselves are generated during the build from the Flow declaration files.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/styled-components-polished)Star history chart for your README
[](https://hysenlabs.com/projects/styled-components-polished)Was this useful?