{"id":12750,"library":"polished","title":"Polished","description":"Polished is a lightweight, cross-framework toolset for writing styles in JavaScript, providing Sass-style helper functions and mixins. Currently at version 4.3.1, it receives regular maintenance updates with a focus on bug fixes, performance improvements, and new CSS feature support, as seen in recent v4.2.x and v44.3.x releases. Key differentiators include its functional, curried approach to color manipulation, extensive cross-framework compatibility (working with styled-components, emotion, JSS, etc.), and first-class TypeScript and Flow support. It aims to ease the transition for developers moving from CSS pre-processors to JavaScript-based styling solutions by offering a familiar set of utility functions to enhance productivity and maintain consistency across applications. The library is designed for tree-shaking, promoting optimized bundle sizes by encouraging named imports for individual modules.","status":"active","version":"4.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/styled-components/polished","tags":["javascript","styled-components","polished","emotion","glamor","css-in-js","inline-styles","react","flow","typescript"],"install":[{"cmd":"npm install polished","lang":"bash","label":"npm"},{"cmd":"yarn add polished","lang":"bash","label":"yarn"},{"cmd":"pnpm add polished","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Polished functions should be imported individually for optimal tree-shaking and bundle size reduction. Avoid default or star imports.","wrong":"import polished from 'polished'; polished.lighten(...)","symbol":"lighten","correct":"import { lighten } from 'polished'"},{"note":"While CommonJS `require` might work in some environments, Polished is designed for ESM imports to leverage modern tooling features like tree-shaking. TypeScript users should ensure `moduleResolution: 'node'` in `tsconfig.json`.","wrong":"const { fluidRange } = require('polished')","symbol":"fluidRange","correct":"import { fluidRange } from 'polished'"},{"note":"Importing the entire library via `* as polished` prevents effective tree-shaking, leading to larger bundle sizes than necessary. Stick to named imports.","wrong":"import * as polished from 'polished'; polished.rgba(...)","symbol":"rgba","correct":"import { rgba } from 'polished'"}],"quickstart":{"code":"import { lighten, darken, rgba, fluidRange, em } from 'polished';\n\n// Example: Color manipulation\nconst baseColor = '#663399'; // A deep purple\nconst lightenedColor = lighten(0.2, baseColor);\nconst darkenedColor = darken(0.1, baseColor);\nconst transparentColor = rgba(baseColor, 0.5);\n\nconsole.log('Original color:', baseColor);\nconsole.log('Lightened color:', lightenedColor);\nconsole.log('Darkened color:', darkenedColor);\nconsole.log('Transparent color (50% opacity):', transparentColor);\n\n// Example: Responsive typography with fluidRange\n// Defines a font size that scales between 16px and 20px\n// within viewport widths of 400px to 1200px.\nconst responsiveFontProps = fluidRange(\n  { prop: 'font-size', fromSize: '16px', toSize: '20px' },\n  '400px',\n  '1200px'\n);\n\nconsole.log('\\nResponsive font properties (for CSS-in-JS):');\nconsole.log(responsiveFontProps);\n\n// Example: Em unit conversion\nconst emValue = em(16, 14); // 16px based on a 14px root font size\nconsole.log('\\n16px converted to em (base 14px):', emValue); // '1.1428571428571428em'\n\n// Demonstrate functional composition, a key concept for Polished\n// Assuming a 'compose' utility from a library like Ramda or a custom one\n// import { compose } from 'ramda';\n// const makeBrighterAndMoreTransparent = compose(\n//   (color: string) => lighten(0.1, color),\n//   (color: string) => rgba(color, 0.8)\n// );\n// const newColor = makeBrighterAndMoreTransparent('#FF0000');\n// console.log('\\nComposed color (brighter and more transparent red):', newColor);\n","lang":"typescript","description":"Demonstrates core Polished functionalities including color manipulation (lighten, darken, rgba), responsive design helpers (fluidRange), and unit conversion (em). It highlights the recommended named import pattern."},"warnings":[{"fix":"Refactor your import statements to use named imports for each function you utilize from the library.","message":"To ensure optimal bundle size, always use named imports for individual Polished functions (e.g., `import { lighten } from 'polished'`). Avoid `import * as polished from 'polished'` or `import polished from 'polished'` as these prevent tree-shaking.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"No direct action is required from users, but be aware of the removal of this internal dependency if you had specific monitoring setups that might have inadvertently relied on it. Update to v4.1.1+ or v3.7.1+ LTS to ensure removal.","message":"The `scarf` analytics package was removed due to yarn incompatibilities and GDPR compliance concerns. This change addresses potential supply chain and privacy issues.","severity":"breaking","affected_versions":">=4.1.1, >=3.7.1"},{"fix":"Add or verify `\"moduleResolution\": \"node\"` within the `compilerOptions` in your `tsconfig.json`.","message":"When using Polished with TypeScript, ensure your `tsconfig.json` includes `\"moduleResolution\": \"node\"` to correctly resolve module imports and type definitions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add `.*/node_modules/polished/.*` to the `[ignore]` section of your `.flowconfig`.","message":"If you encounter Flow type errors originating from the `polished` package, it may be due to Flow version incompatibilities. You can ignore Polished's source in your Flow configuration.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install and configure `babel-plugin-transform-object-rest-spread` or a compatible Babel preset in your project's Babel configuration.","message":"Using object spread properties (e.g., `{ ...other }`) within your styles that integrate with Polished requires a Babel plugin such as `transform-object-rest-spread` or a preset like `stage-3`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update `polished` to v4.3.1 or newer if you are using Rollup in your build pipeline and encountering related issues. Alternatively, ensure your Rollup version is compatible with older Polished versions.","message":"Versions prior to v4.3.1 might experience incompatibility issues with later versions of Rollup due to the `annotate-pure-calls` plugin. This was resolved in v4.3.1.","severity":"breaking","affected_versions":"<4.3.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `import * as polished from 'polished'` or `import polished from 'polished'` to `import { lighten } from 'polished'` for the specific function being used.","cause":"Attempting to use a Polished function via a default or star import, which prevents bundlers like Webpack from tree-shaking and correctly exposing the named export at runtime.","error":"TypeError: (0 , polished__WEBPACK_IMPORTED_MODULE_2__.lighten) is not a function"},{"fix":"Ensure `\"moduleResolution\": \"node\"` is set within the `compilerOptions` in your `tsconfig.json`.","cause":"TypeScript's module resolution failing to locate the package's type definitions.","error":"TS2307: Cannot find module 'polished' or its corresponding type declarations."},{"fix":"Switch to ESM named imports: `import { functionName } from 'polished';`.","cause":"Using CommonJS `require('polished')` syntax in an environment configured for ECMAScript Modules (ESM), typically in modern Node.js projects with `\"type\": \"module\"` in `package.json` or in browser environments after bundling.","error":"ReferenceError: require is not defined in ES module scope"}],"ecosystem":"npm"}