Top Related Projects
JSS is an authoring tool for CSS which uses JavaScript as a host language.
👩🎤 CSS-in-JS library designed for high performance style composition
A utility-first CSS framework for rapid UI development.
Sass makes CSS fun!
Less. The dynamic stylesheet language.
Transforming styles with JS plugins
Quick Overview
Polished is a lightweight toolset for writing styles in JavaScript, primarily designed to work with styled-components. It provides a collection of utility functions for common CSS tasks, making it easier to create and maintain consistent styles across a project.
Pros
- Enhances styled-components with a wide range of utility functions
- Improves code reusability and maintainability
- Provides type definitions for TypeScript users
- Modular architecture allows for tree-shaking, reducing bundle size
Cons
- Adds an additional dependency to your project
- Learning curve for developers unfamiliar with functional CSS approaches
- Some functions may have performance implications if overused
- Limited browser support for certain advanced features
Code Examples
- Using the
rgba
function to create a transparent color:
import { rgba } from 'polished'
const Button = styled.button`
background-color: ${rgba('#000000', 0.5)};
`
- Utilizing the
rem
function for consistent sizing:
import { rem } from 'polished'
const Heading = styled.h1`
font-size: ${rem('24px')};
margin-bottom: ${rem('16px')};
`
- Applying the
darken
function for hover effects:
import { darken } from 'polished'
const Link = styled.a`
color: #007bff;
&:hover {
color: ${darken(0.2, '#007bff')};
}
`
Getting Started
To use Polished in your project, first install it via npm or yarn:
npm install polished
# or
yarn add polished
Then, import and use the functions in your styled-components:
import styled from 'styled-components'
import { lighten, rem } from 'polished'
const Button = styled.button`
background-color: #007bff;
padding: ${rem('8px')} ${rem('16px')};
&:hover {
background-color: ${lighten(0.1, '#007bff')};
}
`
This example creates a button with a blue background that lightens on hover, using consistent rem units for padding.
Competitor Comparisons
JSS is an authoring tool for CSS which uses JavaScript as a host language.
Pros of JSS
- More flexible and powerful, allowing for dynamic styles and complex logic
- Better performance for large-scale applications due to its optimized runtime
- Supports server-side rendering out of the box
Cons of JSS
- Steeper learning curve, especially for developers used to traditional CSS
- Requires additional setup and configuration compared to Polished
- Less focused on utility functions, more on creating entire styling systems
Code Comparison
JSS:
const styles = {
myButton: {
color: 'green',
margin: {
top: 5,
right: 0,
bottom: 0,
left: '1rem'
}
}
};
Polished:
import { margin } from 'polished';
const styles = css`
color: green;
${margin(5, 0, 0, '1rem')}
`;
Summary
JSS is a more comprehensive styling solution, offering greater flexibility and performance for large-scale applications. It excels in creating dynamic styles and complex styling systems. However, it comes with a steeper learning curve and requires more setup.
Polished, on the other hand, focuses on providing utility functions to enhance CSS-in-JS libraries like styled-components. It's easier to integrate into existing projects and has a gentler learning curve, but may not offer the same level of flexibility and performance optimization as JSS for complex applications.
👩🎤 CSS-in-JS library designed for high performance style composition
Pros of emotion
- More flexible and versatile, supporting both object and string styles
- Better performance due to its smaller bundle size and optimized runtime
- Offers a wider range of styling options, including server-side rendering and theming
Cons of emotion
- Steeper learning curve, especially for developers new to CSS-in-JS
- Less established ecosystem compared to styled-components
- May require additional configuration for certain advanced use cases
Code Comparison
emotion:
import { css } from '@emotion/react'
const style = css`
color: hotpink;
&:hover { color: darkorchid; }
`
polished:
import { lighten } from 'polished'
const Button = styled.button`
background: ${lighten(0.2, '#000')};
`
Summary
emotion is a more comprehensive CSS-in-JS solution, offering greater flexibility and performance. polished, on the other hand, is a utility library designed to work alongside styled-components or other CSS-in-JS libraries, providing helpful functions for color manipulation, size calculations, and other common styling tasks. While emotion can handle most styling needs on its own, polished excels at providing specific, reusable styling functions that can enhance any CSS-in-JS workflow.
A utility-first CSS framework for rapid UI development.
Pros of Tailwind CSS
- Rapid development with utility-first approach
- Highly customizable with a comprehensive configuration system
- Large and active community with extensive documentation
Cons of Tailwind CSS
- Steeper learning curve for developers used to traditional CSS
- Can lead to verbose HTML with multiple utility classes
Code Comparison
Tailwind CSS:
<button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">
Button
</button>
Polished:
import { lighten, darken } from 'polished'
const Button = styled.button`
background: ${props => props.primary ? '#0077CC' : '#6C757D'};
color: white;
padding: 0.5em 1em;
border: none;
border-radius: 3px;
&:hover {
background: ${props => lighten(0.1, props.primary ? '#0077CC' : '#6C757D')};
}
`
Tailwind CSS focuses on utility classes for rapid development, while Polished provides a set of tools for writing styled-components with more traditional CSS-in-JS approach. Tailwind CSS offers a more comprehensive design system out of the box, whereas Polished gives more flexibility for custom styling logic.
Sass makes CSS fun!
Pros of Sass
- More mature and widely adopted in the industry
- Offers advanced features like mixins, nesting, and built-in functions
- Supports both .scss and .sass syntax options
Cons of Sass
- Requires a compilation step before use in browsers
- Can lead to larger CSS files if not optimized properly
- Learning curve for developers new to preprocessors
Code Comparison
Sass:
$primary-color: #3498db;
@mixin button-styles($color) {
background-color: $color;
color: white;
padding: 10px 15px;
}
.button {
@include button-styles($primary-color);
}
Polished:
import { darken, lighten } from 'polished';
const primaryColor = '#3498db';
const Button = styled.button`
background-color: ${primaryColor};
color: white;
padding: 10px 15px;
&:hover {
background-color: ${darken(0.1, primaryColor)};
}
`;
Both Sass and Polished offer powerful tools for styling, but they cater to different ecosystems. Sass is a preprocessor that works with traditional CSS workflows, while Polished integrates seamlessly with CSS-in-JS solutions like styled-components. The choice between them often depends on the project's architecture and the team's preferences.
Less. The dynamic stylesheet language.
Pros of Less.js
- Mature and widely adopted CSS preprocessor with a large ecosystem
- Supports browser-side compilation, enabling dynamic styling
- Offers variables, mixins, and functions for enhanced CSS authoring
Cons of Less.js
- Requires compilation step before use in production environments
- Limited to CSS-specific functionality and syntax
- Steeper learning curve for developers new to CSS preprocessors
Code Comparison
Less.js:
@primary-color: #3498db;
.button {
background-color: @primary-color;
&:hover {
background-color: darken(@primary-color, 10%);
}
}
Polished:
import { darken } from 'polished';
const primaryColor = '#3498db';
const Button = styled.button`
background-color: ${primaryColor};
&:hover {
background-color: ${darken(0.1, primaryColor)};
}
`;
Key Differences
- Less.js is a CSS preprocessor, while Polished is a utility library for CSS-in-JS
- Less.js requires a separate compilation step, whereas Polished works directly with JavaScript
- Polished integrates seamlessly with styled-components and other CSS-in-JS libraries
- Less.js has a more CSS-like syntax, while Polished uses JavaScript functions for manipulations
Both tools aim to enhance CSS authoring, but they cater to different development workflows and preferences.
Transforming styles with JS plugins
Pros of PostCSS
- Highly extensible with a large ecosystem of plugins
- Can be used with any CSS preprocessor or vanilla CSS
- Offers more comprehensive CSS processing capabilities
Cons of PostCSS
- Steeper learning curve, especially when configuring multiple plugins
- Requires more setup and configuration compared to Polished
Code Comparison
PostCSS (with autoprefixer plugin):
.example {
display: flex;
}
Processed output:
.example {
display: -webkit-box;
display: -ms-flexbox;
display: flex;
}
Polished:
import { flexbox } from 'polished'
const styles = {
...flexbox()
}
Key Differences
- PostCSS is a tool for transforming CSS with JavaScript plugins, while Polished is a lightweight toolset for writing styles in JavaScript
- PostCSS operates on CSS files or strings, whereas Polished provides utility functions for use in JavaScript
- PostCSS offers more extensive CSS processing capabilities, while Polished focuses on providing a set of styling helpers and mixins
Use Cases
- PostCSS: Large projects requiring extensive CSS processing and transformation
- Polished: Projects using CSS-in-JS solutions, particularly with styled-components
Both tools have their strengths and can be valuable depending on the project requirements and preferred styling approach.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
A lightweight toolset for writing styles in JavaScript. â¨
npm install --save polished
# or if you're using yarn
yarn add polished
Want to write styles in JavaScript, but also want Sass-style helper functions and mixins? Need a consistent color palette throughout your app? ⨠polished
is for you!
- Make your app look great without stress
- Cross framework compatible: No matter if you're using
styled-components
, emotion, jss, aphrodite, radium, or plain inline styles, as long as you're writing your styles in JavaScript you can use polished! - Switching from a pre-processor to styles in JS made easy
Docs
See the full documentation at polished.js.org!
Usage
⨠polished
modules are meant to be used as stand-alone imports. You should avoid importing the entire library directly:
import { clearFix, animation } from 'polished'
import * as polished from 'polished
import polished from 'polished'
When ⨠polished
modules are imported properly, tree shaking in webpack and Rollup can be leveraged to reduce your bundle size.
Browser Support
All Evergreen Browsers + IE11
As of v3.6.X we support >0.5%, not dead, ie >= 11, not op_mini all
for all our builds.
Flow Type Definitions
⨠polished
has first-class Flow support with zero configuration to assist you in finding type errors while using our modules.
Ignore ⨠polished source
Flow frequently updates and it is possible that the version you are running may cause you to run into errors coming from the polished
package in your node_modules
directory. You can add the following lines to your .flowconfig
to ignore polished
in those cases:
[ignore]
.*/node_modules/polished/.*
TypeScript Definitions
⨠polished
has TypeScript definitions to allow the library to be used in any TypeScript project. You will need to set moduleResolution
to node
in your tsconfig.json
in order to use ⨠polished
with TypeScript.
Babel plugin
You can optionally also use babel-plugin-polished
to compile the static function calls out and remove the (already tiny) runtime performance impact of using ⨠polished
.
Object Spread Properties
In the documentation you will see examples using object spread properties ({ ...other }
). To enable this syntax in your project add the transform-object-rest-spread
plugin (or the stage-3
preset to enable all stage three features) to your Babel configuration.
Why?
When writing styles in JavaScript, many people need Sass-style helper functions to be productive. ⨠polished
brings them to you in a nice, lightweight package tailor-made for styles in JavaScript.
The main difference with Sass is that it's written in a functional style and all color functions are curried. This means you can compose them together into your own reusable helpers with a compose
function of your choice:
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))
Why not package-xyz
?
First of all, we didn't find another library that had everything we needed, and we don't care about installing a dozen packages separately.
Specifically most other packages that provide color functions do so in an object-oriented style, often with a fluent API that's very different from the Sass-style helpers. This means people that aren't very familiar with JavaScript might shy away from using them.
⨠polished
was made as a standard library for everybody, no matter if they know JS inside out or not.
Compatibility
⨠polished is compatible with any library that accepts styles as JS objects. This includes, but is by far not limited to, styled-components
, radium, aphrodite, glamor, glamorous, jss and many more!
No matter if you're using inline styles or CSS-in-JS, polished is for you.
Contributors
This project exists thanks to all the people who contribute. [Contribute].
Backers
Thank you to all our backers! ð [Become a backer]
Sponsors
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]
License
Copyright © 2016-2021 Brian Hough, Maximilian Stoiber, & Nik Graf. Licensed under the MIT License, see LICENSE.md for more information!
Top Related Projects
JSS is an authoring tool for CSS which uses JavaScript as a host language.
👩🎤 CSS-in-JS library designed for high performance style composition
A utility-first CSS framework for rapid UI development.
Sass makes CSS fun!
Less. The dynamic stylesheet language.
Transforming styles with JS plugins
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot