# Styled Components

> This is a **web-specific** API and you **won't** be able to use it in react-native.

---

## Referring to other components

> This is a **web-specific** API and you **won't** be able to use it in react-native.

There are many ways to apply contextual overrides to a component's styling. That being said,
it rarely is easy without rigging up a well-known targeting CSS selector paradigm
and then making them accessible for use in interpolations.

styled-components solves this use case cleanly via the "component selector" pattern. Whenever
a component is created or wrapped by the `styled()` factory function, it is also assigned a
stable CSS class for use in targeting. This allows for extremely powerful composition patterns
without having to fuss around with naming and avoiding selector collisions.

A practical example: here, our Icon component defines its response to the parent Link being hovered:

```react
const Link = styled.a`
  display: flex;
  align-items: center;
  padding: 5px 10px;
  background: papayawhip;
  color: #BF4F74;
`;

const Icon = styled.svg`
  flex: none;
  transition: fill 0.25s;
  width: 48px;
  height: 48px;

  ${Link}:hover & {
    fill: rebeccapurple;
  }
`;

const Label = styled.span`
  display: flex;
  align-items: center;
  line-height: 1.2;

  &::before {
    content: '◀';
    margin: 0 10px;
  }
`;

render(
  <Link href="#">
    <Icon viewBox="0 0 20 20">
      <path d="M10 15h8c1 0 2-1 2-2V3c0-1-1-2-2-2H2C1 1 0 2 0 3v10c0 1 1 2 2 2h4v4l4-4zM5 7h2v2H5V7zm4 0h2v2H9V7zm4 0h2v2h-2V7z"/>
    </Icon>
    <Label>Hovering my parent changes my style!</Label>
  </Link>
);
```

We could have nested the color-changing rule within our Link component, but then we'd have to
consider both sets of rules to understand why Icon behaves as it does.

### Caveat

This behaviour is only supported within the context of _Styled_ Components:
attempting to mount `B` in the following example will fail because component
`A` is an instance of `React.Component` not a Styled Component.

```tsx
class A extends React.Component {
  render() {
    return <div />
  }
}

const B = styled.div`
  ${A} {
  }
`
```

The error thrown - `Cannot call a class as a function` - occurs because the
styled component is attempting to call the component as an interpolation function.

However, wrapping `A` in a `styled()` factory makes it eligible for interpolation -- just
make sure the wrapped component passes along `className`.

```tsx
class A extends React.Component {
  render() {
    return <div className={this.props.className} />
  }
}

const StyledA = styled(A)``

const B = styled.div`
  ${StyledA} {
  }
`
```

---

## Existing CSS

There are a couple of implementation details that you should be aware of, if you choose to use
styled-components together with existing CSS.

styled-components generates an actual stylesheet with classes, and attaches those classes to
the DOM nodes of styled components via the `className` prop.
It injects the generated stylesheet at the end of the head of the document during runtime.

### Styling normal React components

If you use the `styled(MyComponent)` notation and `MyComponent` does not
render the passed-in `className` prop, then no styles will be applied.
To avoid this issue, make sure your component attaches the passed-in `className` to a DOM node:

```tsx
class MyComponent extends React.Component {
  render() {
    // Attach the passed-in className to the DOM node
    return <div className={this.props.className} />
  }
}
```

If you have pre-existing styles with a class, you can combine the global class with the
passed-in one:

```tsx
class MyComponent extends React.Component {
  render() {
    // Attach the passed-in className to the DOM node
    return <div className={`some-global-class ${this.props.className}`} />
  }
}
```

### Issues with specificity

If you apply a global class together with a styled component class, the result might not be
what you're expecting. If a property is defined in both classes with the same specificity,
the last one will win.

```tsx
// MyComponent.js
const MyComponent = styled.div`background-color: green;`;

// my-component.css
.red-bg {
  background-color: red;
}

// For some reason this component still has a green background,
// even though you're trying to override it with the "red-bg" class!
<MyComponent className="red-bg" />
```

In the above example the styled component class takes precedence over the global class, since
styled-components injects its styles during runtime at the end of the `<head>` by default.
Thus its styles win over other single classname selectors.

One solution is to bump up the specificity of the selectors in your stylesheet:

```css
/* my-component.css */
.red-bg.red-bg {
  background-color: red;
}
```

### Avoiding conflicts with third-party styles and scripts

If you deploy styled-components on a page you don't fully control, you may need to take
precautions to ensure that your component styles don't conflict with those of the host page.

The most common problem is insufficient specificity. For example, consider a host page with this
style rule:

```css
body.my-body button {
  padding: 24px;
}
```

Since the rule contains a classname and two tag names, it has higher specificity than the single
classname selector generated by this styled component:

```tsx
styled.button`
  padding: 16px;
`
```

There's no way to give your components complete immunity from the host page's styles, but you can
at least boost the specificity of their style rules with
[babel-plugin-styled-components-css-namespace](https://github.com/QuickBase/babel-plugin-styled-components-css-namespace),
which allows you to specify a CSS namespace for all of your styled components. A good namespace
would be something like `#my-widget`, if all of your styled-components render in a container
with `id="my-widget"`, since ID selectors have more specificity than any number of classnames.

A rarer problem is conflicts between two instances of styled-components on the page. You can avoid
this by defining `process.env.SC_ATTR` in the code bundle with your styled-components instance.
This value overrides the default `<style>` tag attribute, `data-styled` (`data-styled-components` in v3 and lower), allowing
each styled-components instance to recognize its own tags.

---

## Refs | v4

Passing a `ref` prop to a styled component will give you one of two things depending on the styled target:

- the underlying DOM node (if targeting a basic element, e.g. `styled.div`)
- a React component instance (if targeting a custom component e.g. extended from `React.Component`)

```react
const Input = styled.input`
  padding: 0.5em;
  margin: 0.5em;
  color: #BF4F74;
  background: papayawhip;
  border: none;
  border-radius: 3px;
`;

class Form extends React.Component {
  constructor(props) {
    super(props);
    this.inputRef = React.createRef();
  }

  render() {
    return (
      <Input
        ref={this.inputRef}
        placeholder="Hover to focus!"
        onMouseEnter={() => {
          this.inputRef.current.focus()
        }}
      />
    );
  }
}

render(
  <Form />
);
```

> Using an older version of styled-components (below 4.0.0) or of React? Use the [`innerRef` prop](/docs/api#innerref-prop) instead.

---

## Security

Since styled-components allows you to use arbitrary input as interpolations, you must be
careful to sanitize that input. Using user input as styles can lead to any CSS being evaluated in the user's
browser that an attacker can place in your application.

This example shows how bad user input can even lead to API endpoints being called on a user's
behalf.

```tsx
// Oh no! The user has given us a bad URL!
const userInput = '/api/withdraw-funds'

const ArbitraryComponent = styled.div`
  background: url(${userInput});
  /* More styles here... */
`
```

Be very careful! This is obviously a made-up example, but CSS injection can be unobvious and
have bad repercussions. Some IE versions even execute arbitrary JavaScript within url declarations.

There is an upcoming standard to sanitize CSS from JavaScript, [`CSS.escape`](https://developer.mozilla.org/en-US/docs/Web/API/CSS/escape). It's not very well supported across browsers yet, so we recommend using the [polyfill by Mathias Bynens](https://github.com/mathiasbynens/CSS.escape) in your app.

---

## Server Side Rendering | v2+

styled-components supports concurrent server side rendering, with stylesheet rehydration.
The basic idea is that everytime you render your app on the server, you can create
a `ServerStyleSheet` and add a provider to your React tree, that accepts styles
via a context API.

This doesn't interfere with global styles, such as `keyframes` or `createGlobalStyle` and
allows you to use styled-components with React DOM's various SSR APIs.

### Tooling setup

In order to reliably perform server side rendering and have the client side bundle pick up without issues, you'll need to use our [babel plugin](/docs/tooling#babel-plugin). It prevents checksum mismatches by adding a deterministic ID to each styled component. Refer to the [tooling documentation](/docs/tooling#serverside-rendering) for more information.

For TypeScript users, our resident TS guru Igor Oleinikov put together a [TypeScript plugin](/docs/tooling#typescript-plugin) for the webpack ts-loader / awesome-typescript-loader toolchain that accomplishes some similar tasks.

If possible, we definitely recommend using the babel plugin though because it is updated the most frequently. It's now possible to [compile TypeScript using Babel](https://babeljs.io/docs/en/babel-preset-typescript), so it may be worth switching off TS loader and onto a pure Babel implementation to reap the ecosystem benefits.

### Example

The basic API goes as follows:

```tsx
import { renderToString } from 'react-dom/server';
import { ServerStyleSheet } from 'styled-components';

const sheet = new ServerStyleSheet();
try {
  const html = renderToString(sheet.collectStyles(<YourApp />));
  const styleTags = sheet.getStyleTags(); // or sheet.getStyleElement();
} catch (error) {
  // handle error
  console.error(error);
} finally {
  sheet.seal();
}
```

The `collectStyles` method wraps your element in a provider. Optionally you can use
the `StyleSheetManager` provider directly, instead of this method. Just make sure not to
use it on the client-side.

```tsx
import { renderToString } from 'react-dom/server';
import { ServerStyleSheet, StyleSheetManager } from 'styled-components';

const sheet = new ServerStyleSheet();
try {
  const html = renderToString(
    <StyleSheetManager sheet={sheet.instance}>
      <YourApp />
    </StyleSheetManager>
  );
  const styleTags = sheet.getStyleTags(); // or sheet.getStyleElement();
} catch (error) {
  // handle error
  console.error(error);
} finally {
  sheet.seal();
}
```

The `sheet.getStyleTags()` returns a string of multiple `<style>` tags.
You need to take this into account when adding the CSS string to your HTML output.

Alternatively the `ServerStyleSheet` instance also has a `getStyleElement()` method
that returns an array of React elements.

If rendering fails for any reason it's a good idea to use `try...catch...finally` to ensure that the `sheet` object will always be available for garbage collection. Make sure `sheet.seal()` is only called after `sheet.getStyleTags()` or `sheet.getStyleElement()` have been called otherwise a different error will be thrown.

> `sheet.getStyleTags()` and `sheet.getStyleElement()` can only be called after your element is rendered. As a result, components from `sheet.getStyleElement()` cannot be combined with `<YourApp />` into a larger component.

### Next.js

#### With Babel

Basically you need to add a custom `pages/_document.js` (if you don't have one). Then [copy the logic](https://github.com/vercel/next.js/blob/canary/examples/with-styled-components-babel/pages/_document.tsx) for styled-components to inject the server side rendered styles into the `<head>`.

Refer to [our example](https://github.com/vercel/next.js/tree/canary/examples/with-styled-components-babel) in the Next.js repo for an up-to-date usage example.

#### With SWC

[Since version 12](https://nextjs.org/blog/next-12), Next.js uses a Rust compiler called SWC. If you're not using any babel plugin, you should refer to [this example](https://github.com/vercel/next.js/tree/canary/examples/with-styled-components) instead.

On this version, you [only need to add](https://github.com/vercel/next.js/blob/canary/examples/with-styled-components/next.config.js) `styledComponents: true,` at the compiler options in the `next.config.js` file and modify `_document` file with `getInitialProps` as in this [example](https://github.com/vercel/next.js/blob/canary/examples/with-styled-components/pages/_document.tsx) to support SSR.

#### App directory

For routes defined in the `app/` directory, in Next.js v13+, you'll need to put a styled-components registry in one of your layout files, as [described in Next.js docs](https://nextjs.org/docs/app/building-your-application/styling/css-in-js#styled-components). Note that this depends on styled-components v6+. Also note that the `'use client'` directive is used - so while your page will be server-side rendered, styled-components will still appear in your client bundle.

### Gatsby

[Gatsby](https://www.gatsbyjs.org/) has an official plugin that enables server-side rendering for styled-components.

Refer to [the plugin's page](https://www.gatsbyjs.org/packages/gatsby-plugin-styled-components/) for setup and usage instructions.

### Streaming Rendering

styled-components offers a streaming API for use with [ReactDOMServer.renderToNodeStream()](https://reactjs.org/docs/react-dom-server.html#rendertonodestream). There are two parts to a streaming implementation:

_On the server:_

`ReactDOMServer.renderToNodeStream` emits a "readable" stream that styled-components wraps. As whole chunks of HTML are pushed onto the stream, if any corresponding styles are ready to be rendered, a style block is prepended to React's HTML and forwarded on to the client browser.

```tsx
import { renderToNodeStream } from 'react-dom/server';
import styled, { ServerStyleSheet } from 'styled-components';

// if you're using express.js, you'd have access to the response object "res"

// typically you'd want to write some preliminary HTML, since React doesn't handle this
res.write('<html><head><title>Test</title></head><body>');

const Heading = styled.h1`
  color: red;
`;

const sheet = new ServerStyleSheet();
const jsx = sheet.collectStyles(<Heading>Hello SSR!</Heading>);
const stream = sheet.interleaveWithNodeStream(renderToNodeStream(jsx));

// you'd then pipe the stream into the response object until it's done
stream.pipe(res, { end: false });

// and finalize the response with closing HTML
stream.on('end', () => res.end('</body></html>'));
```

_On the client:_

```tsx
import { hydrate } from 'react-dom';

hydrate();
// your client-side react implementation
```

After client-side rehydration is complete, styled-components will take over as usual and inject any further dynamic styles after the relocated streaming ones.

---

## Style Objects

styled-components optionally supports writing CSS as JavaScript objects instead of strings. This is particularly useful when you have existing style objects and want to gradually move to styled-components.

```react
// Static object
const Box = styled.div<{ $background?: string; }>({
  background: '#BF4F74',
  height: '50px',
  width: '50px'
});

// Adapting based on props
const PropsBox = styled.div(props => ({
  background: props.$background,
  height: '50px',
  width: '50px'
}));

render(
  <div>
    <Box />
    <PropsBox $background="blue" />
  </div>
);
```

---

## Tagged Template Literals

Tagged Template Literals are a new feature in ES6. They let you define custom string interpolation rules,
which is how we're able to create styled components.

If you pass no interpolations, the first argument your function receives is an array with a string in it.

```tsx
// These are equivalent:
fn`some string here`;
fn(['some string here']);
```

Once you pass interpolations, the array contains the passed string, split at the positions of the interpolations.
The rest of the arguments will be the interpolations, in order.

```tsx
const aVar = 'good';

// These are equivalent:
fn`this is a ${aVar} day`;
fn(['this is a ', ' day'], aVar);
```

This is a bit cumbersome to work with, but it means that we can receive variables, functions, or mixins
(`css` helper) in styled components and can flatten that into pure CSS.

Speaking of which, during flattening, styled-components ignores interpolations that evaluate to `undefined`, `null`,
`false`, or an empty string (`""`), which means you're free to use
[short-circuit evaluation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_AND#Short-circuit_evaluation)
to conditionally add CSS rules.

```tsx
const Title = styled.h1<{ $upsideDown?: boolean; }>`
  /* Text centering won't break if props.$upsideDown is falsy */
  ${props => props.$upsideDown && 'transform: rotate(180deg);'}
  text-align: center;
`;
```

If you want to learn more about tagged template literals, check out Max Stoiber's article:
[The magic behind 💅🏾 styled-components](https://mxstbr.blog/2016/11/styled-components-magic-explained/)

---

## Theming

styled-components has full theming support by exporting a `<ThemeProvider>` wrapper component.
This component provides a theme to all React components underneath itself via the context API. In the render
tree all styled-components will have access to the provided theme, even when they are multiple levels deep.

To illustrate this, let's create our Button component, but this time we'll pass some variables down
as a theme.

```react
// Define our button, but with the use of props.theme this time
const Button = styled.button`
  font-size: 1em;
  margin: 1em;
  padding: 0.25em 1em;
  border-radius: 3px;

  /* Color the border and text with theme.main */
  color: ${props => props.theme.main};
  border: 2px solid ${props => props.theme.main};
`;

// We are passing a default theme for Buttons that arent wrapped in the ThemeProvider
Button.defaultProps = {
  theme: {
    main: "#BF4F74"
  }
}

// Define what props.theme will look like
const theme = {
  main: "mediumseagreen"
};

render(
  <div>
    <Button>Normal</Button>

    <ThemeProvider theme={theme}>
      <Button>Themed</Button>
    </ThemeProvider>
  </div>
);
```

### Function themes

You can also pass a function for the theme prop. This function will receive the parent theme, that is from
another `<ThemeProvider>` higher up the tree. This way themes themselves can be made contextual.

This example renders our above themed Button and a second one that uses a second ThemeProvider to invert the
background and foreground colors. The function `invertTheme` receives the upper theme and creates a new one.

```react
// Define our button, but with the use of props.theme this time
const Button = styled.button`
  color: ${props => props.theme.fg};
  border: 2px solid ${props => props.theme.fg};
  background: ${props => props.theme.bg};

  font-size: 1em;
  margin: 1em;
  padding: 0.25em 1em;
  border-radius: 3px;
`;

// Define our `fg` and `bg` on the theme
const theme = {
  fg: "#BF4F74",
  bg: "white"
};

// This theme swaps `fg` and `bg`
const invertTheme = ({ fg, bg }) => ({
  fg: bg,
  bg: fg
});

render(
  <ThemeProvider theme={theme}>
    <div>
      <Button>Default Theme</Button>

      <ThemeProvider theme={invertTheme}>
        <Button>Inverted Theme</Button>
      </ThemeProvider>
    </div>
  </ThemeProvider>
);
```

### Getting the theme without styled components

#### via `withTheme` higher-order component

If you ever need to use the current theme outside styled components (e.g. inside big components), you can use
the `withTheme` higher order component.

```tsx
import { withTheme } from 'styled-components'

class MyComponent extends React.Component {
  render() {
    console.log('Current theme: ', this.props.theme)
    // ...
  }
}

export default withTheme(MyComponent)
```

#### via `useContext` React hook | v4

You can also use `useContext` to access the current theme outside of styled components when working with React Hooks.

```tsx
import { useContext } from 'react'
import { ThemeContext } from 'styled-components'

const MyComponent = () => {
  const themeContext = useContext(ThemeContext)

  console.log('Current theme: ', themeContext)
  // ...
}
```

#### via `useTheme` custom hook | v5

You can also use `useTheme` to access the current theme outside of styled components when working with React Hooks.

```tsx
import { useTheme } from 'styled-components'

const MyComponent = () => {
  const theme = useTheme()

  console.log('Current theme: ', theme)
  // ...
}
```

### The `theme` prop

A theme can also be passed down to a component using the `theme` prop.

This is useful to circumvent a missing `ThemeProvider` or to override it.

```react
// Define our button
const Button = styled.button`
  font-size: 1em;
  margin: 1em;
  padding: 0.25em 1em;
  border-radius: 3px;

  /* Color the border and text with theme.main */
  color: ${props => props.theme.main};
  border: 2px solid ${props => props.theme.main};
`;

// Define what main theme will look like
const theme = {
  main: "mediumseagreen"
};

render(
  <div>
    <Button theme={{ main: "royalblue" }}>Ad hoc theme</Button>
    <ThemeProvider theme={theme}>
      <div>
        <Button>Themed</Button>
        <Button theme={{ main: "darkorange" }}>Overridden</Button>
      </div>
    </ThemeProvider>
  </div>
);
```

---

import Code from 'components/Code'
import Table, { Row, Column } from 'components/Table'

### `createGlobalStyle` | v4 | web-only

A helper function to generate a special `StyledComponent` that handles global styles. Normally, styled components are automatically scoped to a local CSS class and therefore isolated from other components. In the case of `createGlobalStyle`, this limitation is removed and things like CSS resets or base stylesheets can be applied.

<Table head={['Arguments', 'Description']}>
  <Row>
    <Column>
      1. <Code>TaggedTemplateLiteral</Code>
    </Column>
    <Column>A tagged template literal with your CSS and interpolations.</Column>
  </Row>
</Table>

Returns a `StyledComponent` that does not accept children. Place it at the top of your React tree and the global styles will be injected when the component is "rendered".

```tsx
import { createGlobalStyle } from 'styled-components'

const GlobalStyle = createGlobalStyle<{ $whiteColor?: boolean; }>`
  body {
    color: ${props => (props.$whiteColor ? 'white' : 'black')};
  }
`

// later in your app

<React.Fragment>
  <GlobalStyle $whiteColor />
  <Navigation /> {/* example of other top-level stuff */}
</React.Fragment>
```

Since the `GlobalStyle` component is a `StyledComponent`, that means it also has access to theming from the [`<ThemeProvider>` component](/docs/api#themeprovider) if provided.

```tsx
import { createGlobalStyle, ThemeProvider } from 'styled-components'

const GlobalStyle = createGlobalStyle<{ $whiteColor?: boolean; }>`
  body {
    color: ${props => (props.$whiteColor ? 'white' : 'black')};
    font-family: ${props => props.theme.fontFamily};
  }
`

// later in your app

<ThemeProvider theme={{ fontFamily: 'Helvetica Neue' }}>
  <React.Fragment>
    <Navigation /> {/* example of other top-level stuff */}
    <GlobalStyle $whiteColor />
  </React.Fragment>
</ThemeProvider>
```

---

import Code from 'components/Code'
import Table, { Row, Column } from 'components/Table'

### `css`

A helper function to generate CSS from a template literal with interpolations. You need to use this if you return a
template literal with functions inside an interpolation due to how tagged template literals work in JavaScript.

If you're interpolating a string you do not need to use this, only if you're interpolating a function.

<Table head={['Arguments', 'Description']}>
  <Row>
    <Column>
      1. <Code>TaggedTemplateLiteral</Code>
    </Column>
    <Column>A tagged template literal with your CSS and interpolations.</Column>
  </Row>
</Table>

Returns an array of interpolations, which is a flattened data structure that you can pass as an interpolation
itself.

```tsx
import styled, { css } from 'styled-components'

interface ComponentProps {
  $complex?: boolean;
  $whiteColor?: boolean;
}

const complexMixin = css<ComponentProps>`
  color: ${props => (props.$whiteColor ? 'white' : 'black')};
`

const StyledComp = styled.div<ComponentProps>`
  /* This is an example of a nested interpolation */
  ${props => (props.$complex ? complexMixin : 'color: blue;')};
`
```

If you leave off the css your function will be `toString()`ed and you'll not get the results
you expected.

---

import CSS from './css.mdx'
import Keyframes from './keyframes.mdx'
import IsStyledComponent from './is-styled-component.mdx'
import WithTheme from './with-theme.mdx'
import CreateGlobalStyle from './create-global-style.mdx'
import ThemeConsumer from './theme-consumer.mdx'
import StyleSheetManager from './style-sheet-manager.mdx'
import UseTheme from './use-theme.mdx'

## Helpers

<CreateGlobalStyle />

<CSS />

<Keyframes />

<StyleSheetManager />

<IsStyledComponent />

<WithTheme />

<UseTheme />

<ThemeConsumer />

---

import Code from 'components/Code'
import Table, { Row, Column } from 'components/Table'

### `isStyledComponent`

A utility to help identify styled components.

<Table head={['Arguments', 'Description']}>
  <Row>
    <Column>
      1. <Code>Function</Code>
    </Column>
    <Column>
      Any function expected to possibly be a styled component or React component
      wrapped in a styled component
    </Column>
  </Row>
</Table>

Returns true if the passed function is a valid styled components-wrapped component class. It can be useful for determining if a component needs to be wrapped such that it can be used as a component selector:

```tsx
import React from 'react'
import styled, { isStyledComponent } from 'styled-components'
import MaybeStyledComponent from './somewhere-else'

let TargetedComponent = isStyledComponent(MaybeStyledComponent)
  ? MaybeStyledComponent
  : styled(MaybeStyledComponent)``

const ParentComponent = styled.div`
  color: royalblue;

  ${TargetedComponent} {
    color: tomato;
  }
`
```

---

import Code from 'components/Code'
import Table, { Row, Column } from 'components/Table'

### `keyframes` | web-only

A helper method to create keyframes for animations.

<Table head={['Arguments', 'Description']}>
  <Row>
    <Column>
      1. <Code>TaggedTemplateLiteral</Code>
    </Column>
    <Column>A tagged template literal with your keyframes inside.</Column>
  </Row>
</Table>

Returns a Keyframes model, to be used in your animation declarations. You can use the `getName()` API on the returned model if you wish to obtain the generated animation name.

> In styled-components v3 and below, the `keyframes` helper directly returned the animation name instead of an object with the `getName` method.

```tsx
import styled, { keyframes } from 'styled-components'

const fadeIn = keyframes`
  0% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
`

const FadeInButton = styled.button`
  animation: 1s ${fadeIn} ease-out;
`
```

If you are composing your style rule as a partial, make sure to use the `css` helper.

```tsx
import styled, { css, keyframes } from 'styled-components'

interface AnimationProps {
  $animationLength: number;
}

const pulse = keyframes`
  0% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
`

const animation = props =>
  css<AnimationProps>`
    ${pulse} ${props.$animationLength} infinite alternate;
  `

const PulseButton = styled.button<AnimationProps>`
  animation: ${animation};
`
```

You can learn more about using animations with styled-components in the [Animations](/docs/basics#animations) section.

---

import Table, { Row, Column } from 'components/Table'
import Code from 'components/Code'

### `StyleSheetManager`

A helper component for modifying how your styles are processed. For a given subtree involving styled-components, you can customize various behaviors like how the CSS runtime processor (stylis) handles styles via userland plugins and option overrides.

<Table head={['Props', 'Description']}>
  <Row>
    <Column>
      <Code>disableCSSOMInjection (v5+)</Code>
    </Column>
    <Column>
      Switches to the slower text node-based CSS injection system for adding styles to the DOM. Useful for integrating with third party tools that haven't been upgraded to consume styles from the CSSOM APIs.
    </Column>
  </Row>

  <Row>
    <Column>
      <Code>disableVendorPrefixes (v5, removed in v6)</Code>
    </Column>
    <Column>Opts the given subtree out of adding legacy CSS properties for rendered components.</Column>
  </Row>

  <Row>
    <Column>
      <Code>enableVendorPrefixes (v6+)</Code>
    </Column>
    <Column>Opts the given subtree into adding legacy CSS properties for rendered components.</Column>
  </Row>

  <Row>
    <Column>
      <Code>sheet</Code>
    </Column>
    <Column>
      <em>Thar be dragons ahead.</em> Create and provide your own StyleSheet if necessary for advanced SSR scenarios.
    </Column>
  </Row>

  <Row>
    <Column>
      <Code>stylisPlugins (v5+)</Code>
    </Column>
    <Column>
      An array of plugins to be run by stylis during compilation. Check out{' '}
      <a href="https://www.npmjs.com/search?q=keywords%3Astylis" target="_blank">
        what's available on npm
      </a>
      .
    </Column>
  </Row>

  <Row>
    <Column>
      <Code>target</Code>
    </Column>
    <Column>
      <em>Thar be dragons ahead.</em> Provide an alternate DOM node to inject styles info.
    </Column>
  </Row>
</Table>

For example if your app is intended for legacy browsers, you may want to enable vendor prefixing for your styles:

```react
// import styled, { StyleSheetManager } from 'styled-components'

const Box = styled.div`
  color: ${props => props.theme.color};
  display: flex;
`

render(
  <StyleSheetManager enableVendorPrefixes>
    <Box>If you inspect me, there are vendor prefixes for the flexbox style.</Box>
  </StyleSheetManager>
)
```

Another example would be enabling right-to-left translation for your styles via the userland `stylis-plugin-rtl` plugin:

```react
// import styled, { StyleSheetManager } from 'styled-components'
// import stylisRTLPlugin from 'stylis-plugin-rtl';

const Box = styled.div`
  background: mediumseagreen;
  border-left: 10px solid red;
`

render(
  <StyleSheetManager stylisPlugins={[stylisRTLPlugin]}>
    <Box>My border is now on the right!</Box>
  </StyleSheetManager>
)
```

---

### `ThemeConsumer` | v4

This is the ["consumer" component](https://reactjs.org/docs/context.html#consumer) created by `React.createContext` as the companion component to `ThemeProvider`. It uses the [render prop pattern](https://reactjs.org/docs/render-props.html) to allow for dynamic access to the theme during rendering.

It passes the current theme (based on a [`ThemeProvider`](/docs/api#themeprovider) higher in your component tree) as an argument to the child function. From this function, you may return further JSX or nothing.

```tsx
import { ThemeConsumer } from 'styled-components'

export default class MyComponent extends React.Component {
  render() {
    return (
      <ThemeConsumer>
        {theme => <div>The theme color is {theme.color}.</div>}
      </ThemeConsumer>
    )
  }
}
```

> All styled components [automatically receive the theme as a prop](/docs/advanced#theming), so this is only necessary if you wish to access the theme for other reasons.

---

### `useTheme` | v5

This is a custom hook to get the current theme from a `ThemeProvider`.

```tsx
import { useTheme } from 'styled-components'

function MyComponent() {
  const theme = useTheme()
  console.log('Current theme: ', theme)

  // ...
}
```

> All styled components [automatically receive the theme as a prop](/docs/advanced#theming), so this is only necessary if you wish to access the theme for other reasons.

---

import Code from 'components/Code'
import Table, { Row, Column } from 'components/Table'

### `withTheme`

This is a higher order component factory to get the current theme from a `ThemeProvider` and
pass it to your component as a `theme` prop.

<Table head={['Arguments', 'Description']}>
  <Row>
    <Column>
      1. <Code>Component</Code>
    </Column>
    <Column>
      Any valid React component that can handle a <Code>theme</Code> prop.
    </Column>
  </Row>
</Table>

Returns the passed component inside a wrapper (higher order component).
The passed component will receive a `theme` prop with the current theme object.

```tsx
import { withTheme } from 'styled-components'

class MyComponent extends React.Component {
  render() {
    console.log('Current theme: ', this.props.theme)
    // ...
  }
}

export default withTheme(MyComponent)
```

> All styled components [automatically receive the theme as a prop](/docs/advanced#theming), so this is only necessary if you wish to access the theme for other reasons.

---

import Code from 'components/Code'
import Table, { Row, Column } from 'components/Table'

### `.extend`

> The `.extend` API was removed in styled-components v4. Use `styled(StyledComponent)` instead. For more information, see: https://github.com/styled-components/styled-components/issues/1546

This is a method that creates a new `StyledComponent` and extends its rules.

<Table head={['Arguments', 'Description']}>
  <Row>
    <Column>
      1. <Code>TaggedTemplateLiteral</Code>
    </Column>
    <Column>A tagged template literal with your CSS and interpolations.</Column>
  </Row>
</Table>

```tsx
import styled from 'styled-components'

const Component = styled.div`
  color: red;
`

const Component2 = Component.extend`
  background: white;
  color: blue;
`
```

Returns a new `StyledComponent` with the new rules merged into the ones of the component
this method was called on.

---

import Extend from './extend.mdx'
import InjectGlobal from './inject-global.mdx'
import InnerRef from './inner-ref.mdx'
import WithComponent from './with-component.mdx'

## Previous APIs

<Extend />

<InjectGlobal />

<InnerRef />

<WithComponent />

---

import Code from 'components/Code'
import Table, { Row, Column } from 'components/Table'

### `injectGlobal`

> The `injectGlobal` API was removed and replaced by `createGlobalStyle` in styled-components v4.

A helper method to write global CSS. It does not return a component, but adds the styles to
the stylesheet directly.

<Table head={['Arguments', 'Description']}>
  <Row>
    <Column>
      1. <Code>TaggedTemplateLiteral</Code>
    </Column>
    <Column>A tagged template literal with your global styles inside.</Column>
  </Row>
</Table>

```tsx
import { injectGlobal } from 'styled-components'

injectGlobal`
  @font-face {
    font-family: "Operator Mono";
    src: url("../fonts/Operator-Mono.ttf");
  }

  body {
    margin: 0;
  }
`
```

We do not encourage the use of this. Try to use it once per app at most, if you
must, contained in a single file. This is an escape hatch. Only use it for the
rare `@font-face` definition or body styling.

---

### `"innerRef"` prop

> The `"innerRef"` prop was removed in styled-components v4 in favor of the [React 16 `forwardRef` API](https://reactjs.org/docs/forwarding-refs.html). Just use the normal `ref` prop instead.

Passing a `ref` prop to a styled component will give you an instance of
the `StyledComponent` wrapper, but not to the underlying DOM node.
This is due to how refs work.
It's not possible to call DOM methods, like `focus`, on our wrappers directly.

To get a ref to the actual, wrapped DOM node, pass the callback to the `innerRef` prop instead.

> We don't support string refs (i.e. `innerRef="node"`), since they're already deprecated in React.

This example uses `innerRef` to save a ref to the styled input and focuses it once the user
hovers over it.

```tsx
const Input = styled.input`
  padding: 0.5em;
  margin: 0.5em;
  color: #BF4F74;
  background: papayawhip;
  border: none;
  border-radius: 3px;
`

class Form extends React.Component {
  render() {
    return (
      <Input
        placeholder="Hover here..."
        innerRef={x => {
          this.input = x
        }}
        onMouseEnter={() => this.input.focus()}
      />
    )
  }
}
```

---

import Code from 'components/Code'
import Table, { Row, Column } from 'components/Table'


### `.withComponent`

> The `withComponent` API was replaced by [`"as"` prop](#as-polymorphic-prop) in styled-components v4, and fully-removed in v6.

This is a method that creates a new `StyledComponent` with a different tag or component
applied to it, but all the same rules of the one it's called on.

<Table head={['Arguments', 'Description']}>
  <Row>
    <Column>
      1. <Code>component</Code> / <Code>tagname</Code>
    </Column>
    <Column>Either a valid react component or a tagname like `'div'`.</Column>
  </Row>
</Table>

Returns a new `StyledComponent` with the new tag / component being applied when it's used.

---

### `css` prop | v4

Sometimes you don't want to create an extra component just to apply a bit of styling. The `css` prop is a convenient way to iterate on your components without settling on fixed component boundaries yet. It works on both normal HTML tags as well as components, and supports everything any styled component supports, including adapting based on props, theming and custom components.

> To enable support for the `css` prop you have to use the [Babel plugin](/docs/tooling#babel-plugin).

```tsx
<div
  css={`
    background: papayawhip;
    color: ${props => props.theme.colors.text};
  `}
/>
<Button
  css="padding: 0.5em 1em;"
/>
```

Under the hood, the Babel plugin turns any element with a `css` prop into a styled component. For example, the above code becomes:

```javascript
import styled from 'styled-components';

const StyledDiv = styled.div`
  background: papayawhip;
  color: ${props => props.theme.colors.text};
`

const StyledButton = styled(Button)`
  padding: 0.5em 1em;
`

<StyledDiv />
<StyledButton />
```

Note that you don't even have to add the import, the Babel plugin does that automatically! (unless you're using the Babel macro, see below)

#### Usage with the Babel macro

> This functionality was removed in v6.1 due to lack of usage and unnecessary bloat for other consumers. [More info](https://github.com/styled-components/styled-components/issues/4064)

You can use the [Babel macro](/docs/tooling#babel-macro) to make this work in `create-react-app`. Unfortunately, Babel macros only run when imported so **the import can not be added automatically.** The above code works perfectly if you add the import to the macro manually:

```tsx
import styled from 'styled-components/macro'

<div
  css={`
    background: papayawhip;
    color: ${props => props.theme.colors.text};
  `}
/>
<Button
  css="padding: 0.5em 1em;"
/>
```

#### Usage with TypeScript

To prevent TypeScript errors on the `css` prop on arbitrary elements, install `@types/styled-components` and add the following import once in your project:

```ts
import {} from 'styled-components/cssprop'
```

See https://github.com/DefinitelyTyped/DefinitelyTyped/issues/31245#issuecomment-446011384 for more information.

If you're using a higher version than v6, you do not need to install `@types/styled-components`. 
Instead, you can directly import the `CSSProp` in your project like this:

```ts
import {} from 'react'
import type { CSSProp } from 'styled-components'

declare module 'react' {
  interface Attributes {
    css?: CSSProp | undefined
  }
}
```

---

import Styled from './styled.mdx'
import TaggedTemplateLiteral from './tagged-template-literal.mdx'
import StyledComponent from './styled-component.mdx'
import ThemeProvider from './theme-provider.mdx'
import CssProp from './css-prop.mdx'

## Primary

<Styled />

<TaggedTemplateLiteral />

<StyledComponent />

<ThemeProvider />

<CssProp />

---

import Code from 'components/Code'
import Table, { Row, Column } from 'components/Table'

### `StyledComponent`

A styled React component. This is returned when you
call `styled.tagname` or `styled(Component)` with styles.

This component can take any prop. It passes it on to the HTML node if it's a valid attribute,
otherwise it only passes it into interpolated functions. (see [Tagged Template Literal](/docs/advanced#tagged-template-literals))

You can pass an arbitrary classname to a styled component without problem and it will be applied
next to the styles defined by the styled call.
(e.g. `<MyStyledComp className="bootstrap__btn" />`)

#### .attrs

This is a chainable method that attaches some props to a styled component.
The first and only argument is an object that will be merged into the rest of the
component's props. The `attrs` object accepts the following values:

<Table head={['Values', 'Description']}>
  <Row>
    <Column>
      <Code>Prop Value</Code>
    </Column>
    <Column>
      These can be of any type, except functions. They'll stay static and
      will be merged into the existing component props.
    </Column>
  </Row>

  <Row>
    <Column>
      <Code>Prop Factory</Code>
    </Column>
    <Column>
      A function that receives the props that are passed into the component
      and computes a value, that is then going to be merged into the
      existing component props.
    </Column>
  </Row>
</Table>

Returns another `StyledComponent`.

```react
// import styled from 'styled-components'

const Input = styled.input.attrs<{ $padding?: string; $small?: boolean; }>(props => ({
  type: 'text',
  size: props.$small ? 5 : undefined,
}))`
  border-radius: 3px;
  border: 1px solid #BF4F74;
  display: block;
  margin: 0 0 1em;
  padding: ${props => props.$padding};

  ::placeholder {
    color: #BF4F74;
  }
`

render(
  <>
    <Input $small placeholder="Small" />
    <Input placeholder="Normal" />
    <Input $padding="2em" placeholder="Padded" />
  </>
)
```

Learn more about this constructor in the [Attaching Additional Props](/docs/basics#attaching-additional-props) section.

#### `"as"` polymorphic prop | v4

If you want to keep all the styling you've applied to a component but just switch out what's being ultimately rendered (be it a different HTML tag or a different custom component), you can use the `"as"` prop to do this at runtime.

```react
// import styled from "styled-components";

const Component = styled.div`
  color: red;
`;

render(
  <Component
    as="button"
    onClick={() => alert('It works!')}
  >
    Hello World!
  </Component>
)
```

This sort of thing is very useful in use cases like a navigation bar where some of the items should be links and some just buttons, but all be styled the same way.

#### "forwardedAs" prop | v4.3

If you choose to wrap another component with the `styled()` HOC that also accepts an `"as"` prop, use `"forwardedAs"` to pass along the desired prop to the wrapped component.

#### Transient props | v5.1

If you want to prevent props meant to be consumed by styled components from being passed to the underlying React node or rendered to the DOM element, you can prefix the prop name with a dollar sign (`$`), turning it into a transient prop.

In this example, `$draggable` isn't rendered to the DOM like `draggable` is.

```react
const Comp = styled.div`
  color: ${props =>
    props.$draggable || 'black'};
`;

render(
  <Comp $draggable="red" draggable="true">
    Drag me!
  </Comp>
);
```

#### shouldForwardProp | v5.1

This is a more dynamic, granular filtering mechanism than transient props. It's handy in situations where multiple higher-order components are being composed together and happen to share the same prop name.`shouldForwardProp` works much like the predicate callback of `Array.filter`. A prop that fails the test isn't passed down to underlying components, just like a transient prop.

Keep in mind that, as in this example, other chainable methods should always be executed after `.withConfig`.

```react
const Comp = styled('div').withConfig({
  shouldForwardProp: (prop) =>
      !['hidden'].includes(prop),
}).attrs({ className: 'foo' })`
  color: red;
  &.foo {
    text-decoration: underline;
  }
`;

render(
  <Comp hidden>
    Drag Me!
  </Comp>
);
```

Optionally, `shouldForwardProp` can take a second parameter that provides access to the default validator function. This function can be used as a fallback, and of course, it also works like a predicate, filtering based on known HTML attributes.

---

import Code from 'components/Code'
import Table, { Row, Column } from 'components/Table'

### `styled`

This is the default export.
This is a low-level factory we use to create the `styled.tagname` helper methods.

<Table head={['Arguments', 'Description']}>
  <Row>
    <Column>
      1. <Code>component</Code> / <Code>tagname</Code>
    </Column>
    <Column>
      Either a valid react component or a tagname like <Code>'div'</Code>.
    </Column>
  </Row>
</Table>

Returns a function that accepts a tagged template literal and turns it into a `StyledComponent`.

```react
// import styled from 'styled-components'

const Button = styled.button`
  background: #BF4F74;
  border-radius: 3px;
  border: none;
  color: white;
`

const TomatoButton = styled(Button)`
  background: tomato;
`

render(
  <>
    <Button>I'm purple.</Button>
    <br />
    <TomatoButton>I'm red.</TomatoButton>
  </>
)
```

You can see this method being introduced in the [Getting started](/docs/basics#getting-started) section.

---

import Code from 'components/Code'
import Table, { Row, Column } from 'components/Table'

### `TaggedTemplateLiteral`

This is what you pass into your styled calls – a tagged template literal.
This is an ES6 language feature. You can learn more about them in the
[Tagged Template Literals](/docs/advanced#tagged-template-literals) section.

<Table head={['Inputs', 'Description']}>
  <Row>
    <Column>
      <Code>Rule</Code>
    </Column>
    <Column>Any CSS rules (string)</Column>
  </Row>
  <Row>
    <Column>
      <Code>Interpolation</Code>
    </Column>
    <Column>
      This can either be a string or a function. Strings are combined with the
      rules as-is. Functions will receive the styled component's props as the
      first and only argument.
    </Column>
  </Row>
</Table>

Read more about how to adapt styling based on props in the
[Adapting based on props](/docs/basics#adapting-based-on-props) section.

The properties that are passed into an interpolated function get attached a special
property, `theme`, which is injected by a higher level `ThemeProvider` component.
Check the section on [Theming](/docs/advanced#theming) for more information on this.

```react
// import styled from 'styled-components'

const padding = '3em'

const Section = styled.section<{ $background?: string; }>`
  color: white;

  /* Pass variables as inputs */
  padding: ${padding};

  /* Adjust the background from the properties */
  background: ${props => props.$background};
`

render(
  <Section $background="royalblue">
    ✨ Magic
  </Section>
)
```

You can also return objects from interpolations or input objects directly, and they'll be
treated as inline styles. However this is highly discouraged, as the CSS syntax has support
for pseudo selectors, media queries, nesting, etc., which the object syntax doesn't.

---

import Table, { Row, Column } from 'components/Table'
import Code from 'components/Code'

### `ThemeProvider`

A helper component for theming. Injects the theme into all styled components anywhere
beneath it in the component tree, via the context API.
Check the section on [Theming](/docs/advanced#theming).

<Table head={['Props', 'Description']}>
  <Row>
    <Column>
      <Code>theme</Code>
    </Column>
    <Column>
      An object (or function returning an object) that will be injected as <Code>theme</Code> into all
      interpolations in styled components beneath the provider.
    </Column>
  </Row>
</Table>

Simple usage:

```react
// import styled, { ThemeProvider } from 'styled-components'

const Box = styled.div`
  color: ${props => props.theme.color};
`

render(
  <ThemeProvider theme={{ color: 'mediumseagreen' }}>
    <Box>I'm mediumseagreen!</Box>
  </ThemeProvider>
)
```

Adding to or replacing an outer theme using nested `ThemeProvider`:

```react
// import styled, { ThemeProvider } from 'styled-components'

const Box = styled.div`
  background-color: ${props => props.theme.bg};
  color: ${props => props.theme.color};
`

render(
  <ThemeProvider theme={{ bg: 'white', color: 'mediumseagreen' }}>
    <Box>
      I'm mediumseagreen with a white background!
      <ThemeProvider theme={outerTheme => ({...outerTheme, bg: 'black'})}>
        <Box>I'm mediumseagreen with a black background!</Box>
      </ThemeProvider>
    </Box>
  </ThemeProvider>
)
```

---

## Supported CSS

Within a styled component, we support all of CSS plus nesting. Since we generate an
actual stylesheet and not inline styles, whatever works in CSS works in styled-components!

```react
const Example = styled.div`
  /* all declarations will be prefixed */
  padding: 2em 1em;
  background: papayawhip;

  /* pseudo selectors work as well */
  &:hover {
    background: #BF4F74;
  }

  /* media queries are no problem */
  @media (max-width: 600px) {
    background: tomato;

    /* nested rules work as expected */
    &:hover {
      background: yellow;
    }
  }

  > p {
    /* descendant-selectors work as well, but are more of an escape hatch */
    text-decoration: underline;
  }

  /* Contextual selectors work as well */
  html.test & {
    display: none;
  }
`;

render(
  <Example>
    <p>Hello World!</p>
  </Example>
);
```

Ampersands (`&`) get replaced by our generated, unique classname for that styled
component, making it easy to have complex logic.

---

### `enzymeFind` | v4

A convenience method for finding instances of a particular styled component within an enzyme wrapper.

```tsx
import { mount } from 'enzyme'
import styled from 'styled-components'
import { enzymeFind } from 'styled-components/test-utils'

const Foo = styled.div`
  color: red;
`

const wrapper = mount(
  <div>
    <Foo>bar</Foo>
  </div>
)

enzymeFind(wrapper, Foo)
```

---

### `findAll` | v3

A convenience method to find all instances of a styled component's rendered DOM node within a given DOM root.

```tsx
import styled from 'styled-components'
import { findAll } from 'styled-components/test-utils'

const Foo = styled.div`
  color: ${props => props.color};
`

/**
 * Somewhere in your app:
 *
 * ReactDOM.render(
 *   <main>
 *     <Foo color="red" />
 *     <Foo color="green" />
 *   </main>, document.body
 * );
 */

// retrieves a NodeList of instances of "Foo" in the body (querySelectorAll under the hood)
findAll(document.body, Foo) // NodeList<HTMLDivElement> | null
```

---

### `find` | v3

A convenience method to find a single instance of a styled component's rendered DOM node within a given DOM root.

```tsx
import styled from 'styled-components'
import { find } from 'styled-components/test-utils'

const Foo = styled.div`
  color: red;
`

/**
 * Somewhere in your app:
 *
 * ReactDOM.render(
 *   <main>
 *     <Foo />
 *   </main>, document.body
 * );
 */

// retrieves the first instance of "Foo" in the body (querySelector under the hood)
find(document.body, Foo) // HTMLDivElement | null
```

---

import Find from './find.mdx'
import FindAll from './find-all.mdx'
import EnzymeFind from './enzyme-find.mdx'

## Test Utilities

<Find />

<FindAll />

<EnzymeFind />

---

## TypeScript | v6

styled-components provides TypeScript definitions which empowers the editing experience in IDEs and increases type safety for TypeScript projects.

> For older versions of styled-components, there are community definitions available via the `@types/styled-components` NPM package.

### Create a declarations file

TypeScript definitions for styled-components can be extended by using [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) since version `v4.1.4` of the definitions.

So the first step is creating a declarations file. Let's name it `styled.d.ts` for example.

```ts
// import original module declarations
import 'styled-components';

// and extend them!
declare module 'styled-components' {
  export interface DefaultTheme {
    borderRadius: string;

    colors: {
      main: string;
      secondary: string;
    };
  }
}
```

React-Native:

```ts
import 'styled-components/native'

declare module 'styled-components/native' {
  export interface DefaultTheme {
    borderRadius: string;

    colors: {
      main: string;
      secondary: string;
    };
  }
}
```

`DefaultTheme` is being used as an interface of `props.theme` out of the box. By default the interface `DefaultTheme` is empty so that's why we need to extend it.

### Create a theme

Now we can create a theme just by using the `DefaultTheme` declared at the step above.

```ts
// my-theme.ts
import { DefaultTheme } from 'styled-components';

const myTheme: DefaultTheme = {
  borderRadius: '5px',

  colors: {
    main: 'cyan',
    secondary: 'magenta',
  },
};

export { myTheme };
```

### Styling components

That's it! We're able to use styled-components just by using any original import.

```tsx
import styled, { createGlobalStyle, css } from 'styled-components';

// theme is now fully typed
export const MyComponent = styled.div`
  color: ${props => props.theme.colors.main};
`;

// theme is also fully typed
export MyGlobalStyle = createGlobalStyle`
  body {
    background-color: ${props => props.theme.colors.secondary};
  }
`;

// and this theme is fully typed as well
export cssHelper = css`
  border: 1px solid ${props => props.theme.borderRadius};
`;
```

### Using custom props

If you are [adapting the styles based on props](https://styled-components.com/docs/basics#adapting-based-on-props), and those props are not part of the base tag / component props, you can tell TypeScript what those extra custom props are, with type arguments like this ([TypeScript `v2.9+` is required](https://github.com/Microsoft/TypeScript/wiki/What%27s-new-in-TypeScript#generic-type-arguments-in-generic-tagged-templates)):

```tsx
import styled from 'styled-components';
import Header from './Header';

interface TitleProps {
  readonly $isActive: boolean;
}

const Title = styled.h1<TitleProps>`
  color: ${(props) => (props.$isActive ? props.theme.colors.main : props.theme.colors.secondary)};
`;
```

Note: if you style a standard tag (like `<h1>` in above example), styled-components [will not pass the custom props](https://styled-components.com/docs/basics#passed-props) (to avoid the [Unknown Prop Warning](https://reactjs.org/warnings/unknown-prop.html)).

However, it will pass all of them to a custom React component:

```tsx
import styled from 'styled-components';
import Header from './Header';

const NewHeader = styled(Header)<{ customColor: string }>`
  color: ${(props) => props.customColor};
`;
// Header will also receive props.customColor
```

If the **customColor** property should not be transferred to the **Header** component, you can leverage [transient props](https://styled-components.com/docs/api#transient-props), by prefixing it with a dollar sign ($):

```tsx
import styled from 'styled-components';
import Header from './Header';

const NewHeader2 = styled(Header)<{ $customColor: string }>`
  color: ${(props) => props.$customColor};
`;
// Header does NOT receive props.$customColor
```

Depending on your use case, you can achieve a similar result by extracting the custom props yourself:

```tsx
import styled from 'styled-components';
import Header, { Props as HeaderProps } from './Header';

const NewHeader3 = styled(({ customColor, ...rest }: { customColor: string } & HeaderProps) => <Header {...rest} />)`
  color: ${(props) => props.customColor};
`;
```

Or using [shouldForwardProp](/docs/api#shouldforwardprop):

```tsx
import styled from 'styled-components';
import Header from './Header';

const NewHeader4 = styled(Header).withConfig({
  shouldForwardProp: (prop) => !['customColor'].includes(prop),
})<{ customColor: string }>`
  color: ${(props) => props.customColor};
`;
```

### Caveat with `className`

When defining a component you will need to mark `className` as optional
in your Props interface:

```tsx
interface LogoProps {
  /* This prop is optional, since TypeScript won't know that it's passed by the wrapper */
  className?: string;
}

class Logo extends React.Component<LogoProps, {}> {
  render() {
    return <div className={this.props.className}>Logo</div>;
  }
}

const LogoStyled = styled(Logo)`
  font-family: 'Helvetica';
  font-weight: bold;
  font-size: 1.8rem;
`;
```

### Caveat with Function Components

To use function components and have typechecking for the props you'll need to define
the component alongside with its type. This is not special to styled-components, this is just
how React works:

```tsx
interface BoxProps {
  theme?: ThemeInterface;
  borders?: boolean;
  className?: string;
}

const Box: React.FunctionComponent<BoxProps> = (props) => <div className={props.className}>{props.children}</div>;

const StyledBox = styled(Box)`
  padding: ${(props) => props.theme.lateralPadding};
`;
```

---

import Code from '../../components/Code'

## Adapting based on props

You can pass a function ("interpolations") to a styled component's template literal to adapt it based on its props.

This button component has a primary state that changes its color. When setting the <Code>$primary</Code> prop to true, we are swapping out its background and text color.

```react
const Button = styled.button<{ $primary?: boolean; }>`
  /* Adapt the colors based on primary prop */
  background: ${props => props.$primary ? "#BF4F74" : "white"};
  color: ${props => props.$primary ? "white" : "#BF4F74"};

  font-size: 1em;
  margin: 1em;
  padding: 0.25em 1em;
  border: 2px solid #BF4F74;
  border-radius: 3px;
`;

render(
  <div>
    <Button>Normal</Button>
    <Button $primary>Primary</Button>
  </div>
);
```

---

## Animations

CSS animations with `@keyframes` aren't scoped to a single component but you still don't want them to be global to avoid name collisions. This is why we export a `keyframes` helper which will generate a unique instance that you can use throughout your app:

```react
// Create the keyframes
const rotate = keyframes`
  from {
    transform: rotate(0deg);
  }

  to {
    transform: rotate(360deg);
  }
`;

// Here we create a component that will rotate everything we pass in over two seconds
const Rotate = styled.div`
  display: inline-block;
  animation: ${rotate} 2s linear infinite;
  padding: 2rem 1rem;
  font-size: 1.2rem;
`;

render(
  <Rotate>&lt; 💅🏾 &gt;</Rotate>
);
```

> Keyframes are not supported by `react-native`. Instead, use the [`ReactNative.Animated` API](https://stackoverflow.com/questions/50891046/rotate-an-svg-in-react-native/50891225#50891225).

Keyframes are lazily injected when they're used, which is how they can be code-split, so you have to use [the `css` helper](/docs/api#css) for shared style fragments:

```javascript
const rotate = keyframes``

// ❌ This will throw an error!
const styles = `
  animation: ${rotate} 2s linear infinite;
`

// ✅ This will work as intended
const styles = css`
  animation: ${rotate} 2s linear infinite;
`
```

> This used to work in v3 and below where we didn't code-split keyframes. If you're upgrading from v3, make sure that all your shared style fragments are using the `css` helper!

---

## Attaching additional props | v2

To avoid unnecessary wrappers that just pass on some props to the rendered component or element, you can use the [`.attrs` constructor](/docs/api#attrs). It allows you to attach additional props (or "attributes") to a component.

This way you can for example attach static props to an element or pass a third-party prop like `activeClassName` to React Router's Link component. Furthermore, you can also attach more dynamic props to a component. The `.attrs` object also takes functions, that receive the props that the component receives. The return value will be merged into the resulting props as well.

Here we render an `Input` component and attach some dynamic and static attributes to it:

```react
const Input = styled.input.attrs<{ $size?: string; }>(props => ({
  // we can define static props
  type: "text",

  // or we can define dynamic ones
  $size: props.$size || "1em",
}))`
  color: #BF4F74;
  font-size: 1em;
  border: 2px solid #BF4F74;
  border-radius: 3px;

  /* here we use the dynamically computed prop */
  margin: ${props => props.$size};
  padding: ${props => props.$size};
`;

render(
  <div>
    <Input placeholder="A small text input" />
    <br />
    <Input placeholder="A bigger text input" $size="2em" />
  </div>
);
```

As you can see, we get access to our newly created props in the interpolations, and the `type` attribute is passed down to the element.

### Overriding .attrs
Notice that when wrapping styled components, `.attrs` are applied from the innermost styled component to the outermost styled component.

This allows each wrapper to **override** nested uses of `.attrs`, similarly to how CSS properties defined later in a stylesheet override previous declarations.

`Input`'s `.attrs` are applied first, and then `PasswordInput`'s `.attrs`:
```react
const Input = styled.input.attrs<{ $size?: string }>((props) => ({
	type: 'text',
	$size: props.$size || '1em',
}))`
	border: 2px solid #bf4f74;
	margin: ${(props) => props.$size};
	padding: ${(props) => props.$size};
`;

// Input's attrs will be applied first, and then this attrs obj
const PasswordInput = styled(Input).attrs({
  type: "password",
})`
  // similarly, border will override Input's border
  border: 2px solid aqua;
`;

render(
  <div>
    <Input placeholder="A bigger text input" $size="2em" />
    <br />
    {/* Notice we can still use the size attr from Input */}
    <PasswordInput placeholder="A bigger password input" $size="2em" />
  </div>
);
```
This is why `PasswordInput` is of a `'password'` type, but still uses the `$size` attribute from `Input`.

---

## Coming from CSS

### How do Styled Components work within a component?

If you're familiar with importing CSS into your components (e.g. like CSSModules) you'll be used to doing something like this:

```tsx
import React from 'react';
import styles from './styles.css';

export default class Counter extends React.Component {
  state = { count: 0 };

  increment = () => this.setState({ count: this.state.count + 1 });
  decrement = () => this.setState({ count: this.state.count - 1 });

  render() {
    return (
      <div className={styles.counter}>
        <p className={styles.paragraph}>{this.state.count}</p>
        <button className={styles.button} onClick={this.increment}>
          +
        </button>
        <button className={styles.button} onClick={this.decrement}>
          -
        </button>
      </div>
    );
  }
}
```

Because a Styled Component is the _combination_ of the element and the rules that style it, we'd write `Counter` like this:

```tsx
import React from 'react';
import styled from 'styled-components';

const StyledCounter = styled.div`
  /* ... */
`;
const Paragraph = styled.p`
  /* ... */
`;
const Button = styled.button`
  /* ... */
`;

export default class Counter extends React.Component {
  state = { count: 0 };

  increment = () => this.setState({ count: this.state.count + 1 });
  decrement = () => this.setState({ count: this.state.count - 1 });

  render() {
    return (
      <StyledCounter>
        <Paragraph>{this.state.count}</Paragraph>
        <Button onClick={this.increment}>+</Button>
        <Button onClick={this.decrement}>-</Button>
      </StyledCounter>
    );
  }
}
```

Note that we added a "Styled" prefix to `StyledCounter` so that the React component `Counter` and the Styled Component `StyledCounter` don't clash names but remain easily identifiable in the React Developer Tools and Web Inspector.

### Define Styled Components outside of the render method

It is important to define your styled components outside of the render method, otherwise it will be recreated on every single render pass. Defining a styled component within the render method will thwart caching and drastically slow down rendering speed, and should be avoided.

Write your styled components the recommended way:

```tsx
const StyledWrapper = styled.div`
  /* ... */
`;

const Wrapper = ({ message }) => {
  return <StyledWrapper>{message}</StyledWrapper>;
};
```

Instead of:

```tsx
const Wrapper = ({ message }) => {
  // WARNING: THIS IS VERY VERY BAD AND SLOW, DO NOT DO THIS!!!
  const StyledWrapper = styled.div`
    /* ... */
  `;

  return <StyledWrapper>{message}</StyledWrapper>;
};
```

**Recommended reading**: [Talia Marcassa](https://twitter.com/talialongname)
wrote a great review of real-world usage, featuring lots of solid practical insights
and comparisons with alternatives, in [Styled Components: To Use or Not to Use?](https://medium.com/building-crowdriff/styled-components-to-use-or-not-to-use-a6bb4a7ffc21)

### Pseudoelements, pseudoselectors, and nesting

The preprocessor we use, [stylis](https://github.com/thysultan/stylis.js), supports scss-like syntax for automatically nesting styles.

Through this preprocessing, styled-components supports some advanced selector patterns:

- `&` a single ampersand refers to **all instances** of the component; it is used for applying broad overrides:

  ```react
  const Thing = styled.div.attrs((/* props */) => ({ tabIndex: 0 }))`
    color: blue;

    &:hover {
      color: red; // <Thing> when hovered
    }

    & ~ & {
      background: tomato; // <Thing> as a sibling of <Thing>, but maybe not directly next to it
    }

    & + & {
      background: lime; // <Thing> next to <Thing>
    }

    &.something {
      background: orange; // <Thing> tagged with an additional CSS class ".something"
    }

    .something-else & {
      border: 1px solid; // <Thing> inside another element labeled ".something-else"
    }
  `

  render(
    <React.Fragment>
      <Thing>Hello world!</Thing>
      <Thing>How ya doing?</Thing>
      <Thing className="something">The sun is shining...</Thing>
      <div>Pretty nice day today.</div>
      <Thing>Don't you think?</Thing>
      <div className="something-else">
        <Thing>Splendid.</Thing>
      </div>
    </React.Fragment>
  )
  ```

- `&&` a double ampersand refers to **an instance** of the component; this is useful if you're doing conditional styling overrides and don't want a style to apply to _all instances_ of a particular component:

  ```react
  const Input = styled.input.attrs({ type: "checkbox" })``;

  const Label = styled.label`
    align-items: center;
    display: flex;
    gap: 8px;
    margin-bottom: 8px;
  `

  const LabelText = styled.span`
    ${(props) => {
      switch (props.$mode) {
        case "dark":
          return css`
            background-color: black;
            color: white;
            ${Input}:checked + && {
              color: blue;
            }
          `;
        default:
          return css`
            background-color: white;
            color: black;
            ${Input}:checked + && {
              color: red;
            }
          `;
      }
    }}
  `;

  render(
    <React.Fragment>
      <Label>
        <Input defaultChecked />
        <LabelText>Foo</LabelText>
      </Label>
      <Label>
        <Input />
        <LabelText $mode="dark">Foo</LabelText>
      </Label>
      <Label>
        <Input defaultChecked />
        <LabelText>Foo</LabelText>
      </Label>
      <Label>
        <Input defaultChecked />
        <LabelText $mode="dark">Foo</LabelText>
      </Label>
    </React.Fragment>
  )
  ```

- `&&` a double ampersand alone has a special behavior called a "precedence boost"; this can be useful if you are dealing with a mixed styled-components and vanilla CSS environment where there might be conflicting styles:

  ```react
   const Thing = styled.div`
     && {
       color: blue;
     }
   `

   const GlobalStyle = createGlobalStyle`
     div${Thing} {
       color: red;
     }
   `

   render(
     <React.Fragment>
       <GlobalStyle />
       <Thing>
         I'm blue, da ba dee da ba daa
       </Thing>
     </React.Fragment>
   )
  ```

If you put selectors in without the ampersand, they will refer to children of the component.

```react
const Thing = styled.div`
  color: blue;

  .something {
    border: 1px solid; // an element labeled ".something" inside <Thing>
    display: block;
  }
`

render(
  <Thing>
    <label htmlFor="foo-button" className="something">Mystery button</label>
    <button id="foo-button">What do I do?</button>
  </Thing>
)
```

---

## Extending Styles

Quite frequently you might want to use a component, but change it slightly for a single case. Now, you could pass in an interpolated function and change them based on some props, but that's quite a lot of effort for overriding the styles once.

To easily make a new component that inherits the styling of another, just wrap it in the `styled()` constructor. Here we use the button from the last section and create a special one, extending it with some color-related styling:

```react
// The Button from the last section without the interpolations
const Button = styled.button`
  color: #BF4F74;
  font-size: 1em;
  margin: 1em;
  padding: 0.25em 1em;
  border: 2px solid #BF4F74;
  border-radius: 3px;
`;

// A new component based on Button, but with some override styles
const TomatoButton = styled(Button)`
  color: tomato;
  border-color: tomato;
`;

render(
  <div>
    <Button>Normal Button</Button>
    <TomatoButton>Tomato Button</TomatoButton>
  </div>
);
```

We can see that the new `TomatoButton` still resembles `Button`, while we have only added two new rules.

In some cases you might want to change which tag or component a styled component renders. This is common when building a navigation bar for example, where there are a mix of anchor links and buttons but they should be styled identically.

For this situation, we have an escape hatch. You can use the [`"as" polymorphic prop`](/docs/api#as-polymorphic-prop) to dynamically swap out the element that receives the styles you wrote:

```react
const Button = styled.button`
  display: inline-block;
  color: #BF4F74;
  font-size: 1em;
  margin: 1em;
  padding: 0.25em 1em;
  border: 2px solid #BF4F74;
  border-radius: 3px;
  display: block;
`;

const TomatoButton = styled(Button)`
  color: tomato;
  border-color: tomato;
`;

render(
  <div>
    <Button>Normal Button</Button>
    <Button as="a" href="#">Link with Button styles</Button>
    <TomatoButton as="a" href="#">Link with Tomato Button styles</TomatoButton>
  </div>
);
```

This works perfectly fine with custom components too!

```react
const Button = styled.button`
  display: inline-block;
  color: #BF4F74;
  font-size: 1em;
  margin: 1em;
  padding: 0.25em 1em;
  border: 2px solid #BF4F74;
  border-radius: 3px;
  display: block;
`;

const ReversedButton = props => <Button {...props} children={props.children.split('').reverse()} />

render(
  <div>
    <Button>Normal Button</Button>
    <Button as={ReversedButton}>Custom Button with Normal Button styles</Button>
  </div>
);
```

---

## Getting Started

`styled-components` utilises tagged template literals to style your components.

It removes the mapping between components and styles. This means that when you're defining your styles, you're actually creating a normal React component, that has your styles attached to it.

This example creates two simple components, a wrapper and a title, with some styles attached to it:

```react
// Create a Title component that'll render an <h1> tag with some styles
const Title = styled.h1`
  font-size: 1.5em;
  text-align: center;
  color: #BF4F74;
`;

// Create a Wrapper component that'll render a <section> tag with some styles
const Wrapper = styled.section`
  padding: 4em;
  background: papayawhip;
`;

// Use Title and Wrapper like any other React component – except they're styled!
render(
  <Wrapper>
    <Title>
      Hello World!
    </Title>
  </Wrapper>
);
```

This is a live editor, so play around with the code to get a feel for what it's like to work with styled-components!

> The CSS rules are automatically vendor prefixed, styled-components takes care of that for you!
>
> Styled components uses [stylis.js](https://stylis.js.org/) package under the hood for prefixing the css rules.
>
> For additional information about the supported prefixes in stylis.js visit their [repository](https://github.com/thysultan/stylis.js).

---

## Installation

Installing styled-components only takes a single command and you're ready to roll:

```
# with npm
npm install styled-components

# with yarn
yarn add styled-components
```

If you use a package manager like [yarn](https://yarnpkg.com/) that supports the ["resolutions"](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/) package.json field, we also highly recommend you add an entry to it as well corresponding to the major version range. This helps avoid an entire class of problems that arise from multiple versions of styled-components being installed in your project.

In `package.json`:

```json
{
  "resolutions": {
    "styled-components": "^5"
  }
}
```

> It's highly recommended (but not required) to also use the [Babel plugin](/docs/tooling#babel-plugin). It offers many benefits like more legible class names, server-side rendering compatibility, smaller bundles, and more.

<details>
  <summary>Click here to see alternative CDN installation instructions</summary>

If you're not using a module bundler or package manager we also have a global ("UMD") build hosted on the [unpkg](http://unpkg.com) CDN. Simply add the following `<script>` tag to the bottom of your HTML file:

```html
<script src="https://unpkg.com/styled-components/dist/styled-components.min.js"></script>
```

Once you've added `styled-components` you will have access to the global `window.styled` variable.

```tsx
const Component = window.styled.div`
  color: red;
`
```

> This style of usage requires the [react CDN bundles](https://reactjs.org/docs/cdn-links.html) and the [`react-is` CDN bundle](https://unpkg.com/react-is/umd/react-is.production.min.js) to be on the page as well (before the styled-components script.)

</details>

---

## Motivation

**styled-components is the result of wondering how we could enhance CSS for styling React component systems.** By focusing on a single use case we managed to optimize the experience for developers as well as the output for end users.

Apart from the improved experience for developers, styled-components provides:

- **Automatic critical CSS**: styled-components keeps track of which components are rendered on a page and injects their styles and nothing else, fully automatically. Combined with code splitting, this means your users load the least amount of code necessary.
- **No class name bugs**: styled-components generates unique class names for your styles. You never have to worry about duplication, overlap or misspellings.
- **Easier deletion of CSS**: it can be hard to know whether a class name is used somewhere in your codebase. styled-components makes it obvious, as every bit of styling is tied to a specific component. If the component is unused (which tooling can detect) and gets deleted, all its styles get deleted with it.
- **Simple dynamic styling**: adapting the styling of a component based on its props or a global theme is simple and intuitive without having to manually manage dozens of classes.
- **Painless maintenance**: you never have to hunt across different files to find the styling affecting your component, so maintenance is a piece of cake no matter how big your codebase is.
- **Automatic vendor prefixing**: write your CSS to the current standard and let styled-components handle the rest.

You get all of these benefits while still writing the CSS you know and love, just bound to individual components.

---

## Passed props

If the styled target is a simple element (e.g. `styled.div`), styled-components passes through any known HTML attribute to the DOM. If it is a custom React component (e.g. `styled(MyComponent)`), styled-components passes through all props.

This example shows how all props of the Input component are passed on to the
DOM node that is mounted, as with React elements.

```react
// Create an Input component that'll render an <input> tag with some styles
const Input = styled.input<{ $inputColor?: string; }>`
  padding: 0.5em;
  margin: 0.5em;
  color: ${props => props.$inputColor || "#BF4F74"};
  background: papayawhip;
  border: none;
  border-radius: 3px;
`;

// Render a styled text input with the standard input color, and one with a custom input color
render(
  <div>
    <Input defaultValue="@probablyup" type="text" />
    <Input defaultValue="@geelen" type="text" $inputColor="rebeccapurple" />
  </div>
);
```

Note how the `$inputColor` prop is not passed to the DOM, but `type` and `defaultValue` are? The `styled` function is smart enough to filter non-standard attributes automatically for you.

---

## React Native

styled-components can be used with React Native in the same way and with the
same import. Try this example with [Snack by Expo](https://snack.expo.io/@danielmschmidt/styled-components).

```tsx
import React from 'react'
import styled from 'styled-components/native'

const StyledView = styled.View`
  background-color: papayawhip;
`

const StyledText = styled.Text`
  color: #BF4F74;
`

class MyReactNativeComponent extends React.Component {
  render() {
    return (
      <StyledView>
        <StyledText>Hello World!</StyledText>
      </StyledView>
    )
  }
}
```

We also support more complex styles (like `transform`), which would normally
be an array, and shorthands (e.g. for `margin`) thanks to
[`css-to-react-native`](https://github.com/styled-components/css-to-react-native)!

> Note that the `flex` property works like CSS shorthand, and not the legacy
> `flex` property in React Native. Setting `flex: 1` sets `flexShrink`
> to `1` in addition to setting `flexGrow` to `1` and `flexBasis` to `0`.

Imagine how you'd write the property in React Native, guess how you'd transfer
it to CSS, and you're probably right:

```tsx
const RotatedBox = styled.View`
  transform: rotate(90deg);
  text-shadow-offset: 10px 5px;
  font-variant: small-caps;
  margin: 5px 7px 2px;
`
```

Some of the differences to the web-version are, that you cannot use the
`keyframes` and `createGlobalStyle` helpers since React Native doesn't support
keyframes or global styles. We will also warn you if you use media queries or
nest your CSS.

> In v2 we support percentages. To make this possible we need to enforce units
> for all shorthands. If you're migrating to v2,
> [a codemod is available](https://github.com/styled-components/styled-components-native-code-mod).

### Simpler usage with the metro bundler

If you'd prefer to just import `styled-components` instead of `styled-components/native`, you can add a [`resolverMainFields` configuration](https://facebook.github.io/metro/docs/configuration#resolvermainfields) that includes `"react-native"`. This used to be supported in metro by default (and currently does work in haul) but appears to have been removed at some point.

---

## Styling any component

The `styled` method works perfectly on all of your own or any third-party component, as long as they attach the passed `className` prop to a DOM element.

> If you are using `react-native` keep in mind to use `style` instead of `className`.

```react
// This could be react-router-dom's Link for example
const Link = ({ className, children }) => (
  <a className={className}>
    {children}
  </a>
);

const StyledLink = styled(Link)`
  color: #BF4F74;
  font-weight: bold;
`;

render(
  <div>
    <Link>Unstyled, boring Link</Link>
    <br />
    <StyledLink>Styled, exciting Link</StyledLink>
  </div>
);
```

> You can also pass tag names into the `styled()` factory call, like so: `styled("div")`. In fact, the `styled.tagname` helpers are just aliases that do the same.

---

## Which browsers are supported?

styled-components supports the same set of browsers as the current React version.

- v2.x (React v0.14+): IE9+, all evergreen browsers
- v3.x (React v0.14+): IE9+, all evergreen browsers
- v4.x (React v16.3+): IE11, IE 9+ (with Map + Set polyfills), all evergreen browsers
- v5.x (React v16.3+): IE11, all evergreen browsers

Evergreen browsers include Chrome and Firefox (and derivatives) as they can be updated regardless of operating system version. Edge and Safari should both also work fine since all versions for the last several years support the relevant APIs.

---

## How do I use styled-components with `create-react-app`?

The basic functionality of the library should work out of the box like any other library.

However, if you want to do server-side rendering or take advantage of some of the advanced capabilities of the [styled-components babel plugin](/docs/tooling#babel-plugin) without ejecting you'll need to set up [`react-app-rewired`](https://github.com/timarney/react-app-rewired) and [`react-app-rewire-styled-components`](https://github.com/withspectrum/react-app-rewire-styled-components).

---

## Why should I avoid declaring styled components in the render method?

By declaring a styled component inside the render method of a react component, you are dynamically creating a new component on every render.
This means that React will have to discard and re-calculate that part of the DOM subtree on each subsequent render, instead of just calculating the difference of what changed between them. This leads to performance bottlenecks and unpredictable behavior.

🚫

```tsx
const Header = () => {
  const Title = styled.h1`
    font-size: 10px;
  `

  return (
    <div>
      <Title />
    </div>
  )
}
```

✅

```tsx
const Title = styled.h1`
  font-size: 10px;
`

const Header = () => {
  return (
    <div>
      <Title />
    </div>
  )
}
```

---

## Why do my DOM nodes have two classes?

Each node actually has two classes connected to it: one is static per component, meaning each element of a styled component has this class. It hasn't any style attached to it. Instead, it's used to quickly identify which styled component a DOM objects belongs to or to make minor changes in the DevTools. It's also used for [component selectors](/docs/advanced#referring-to-other-components). The static class probably will look something like: `.sc-fVOeaW`.

The other is dynamic, meaning it will be different for every element of your styled component with different props, based on what the interpolations result in. It will probably look like `.fVOeaW` (note the lack of "sc" prefix.)

For example, the styled component `<Button />` would render with the same static class every time. If the styles are changed using interpolations, like `<Button secondary />`, then the dynamic class will be a different one, while the static class would remain the same.

---

## Why am I getting a warning about several instances of module on the page?

If you are seeing a warning message in the console like the one below, you probably
have several instances of `styled-components` initialized on the page.

```sh
It looks like there are several instances of "styled-components" initialized in this application. This may cause dynamic styles not rendering properly, errors happening during rehydration process and makes you application bigger without a good reason.

If you are using a building tool like webpack, consider checking your bundle for duplication of the "styled-components" module.
```

This may cause dynamic styles not working properly or even errors during rehydration if
you are using server-side rendering.

### Possible reasons

There are several common reasons for this to happen:

- You have several applications that are using `styled-components` running on the same page
  (e.g., several entry points in webpack are loaded on the same page)
- You have another `styled-components` library somewhere in your dependencies
- You have a monorepo structure for your project (e.g, lerna, yarn workspaces) and `styled-components`
  module is a dependency in more than one package (this one is more or less the same as the previous one)

### Running multiple applications on one page

If you have several applications running on one page, consider using one `styled-components` module for all of them. If you are using webpack, you can use [CommonsChunkPlugin](https://webpack.js.org/plugins/commons-chunk-plugin/)
to create an [explicit vendor chunk](https://webpack.js.org/plugins/commons-chunk-plugin/#explicit-vendor-chunk),
that will contain the `styled-components` module:

```diff
  module.exports = {
    entry: {
+     vendor: ["styled-components"],
      app1: "./src/app.1.js",
      app2: "./src/app.2.js",
    },
    plugins: [
+     new webpack.optimize.CommonsChunkPlugin({
+       name: "vendor",
+       minChunks: Infinity,
+     }),
    ]
  }
```

### Duplicated module in `node_modules`

If you think that the issue is in duplicated `styled-components` module somewhere in your dependencies, there are several ways to check this. You can use `npm ls styled-components`, `yarn list --pattern styled-components` or `find -L ./node_modules | grep /styled-components/package.json` commands in your application folder.

If none of these commands identified the duplication, try analyzing your bundle for multiple instances of `styled-components`. You can just check your bundle source, or use a tool like [source-map-explorer](https://github.com/danvk/source-map-explorer)
or [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer).

If you identified that duplication is the issue that you are encountering there are several things you can try to solve it:

If you are using `npm` you can try running `npm dedupe`. This command searches the local dependencies and tries to simplify the structure by moving common dependencies further up the tree.

> Be aware that `npm dedupe` doesn't work well with symlinked folders (i.e., when you use `npm link`)

If you are using webpack, you can change the way it will [resolve](https://webpack.js.org/configuration/resolve/#resolve-modules)
the `styled-components` module. You can overwrite the default order in which webpack will look for your dependencies and make your application `node_modules` more prioritized than default node module resolution order:

```diff
  resolve: {
+   alias: {
+     "styled-components": path.resolve(appFolder, "node_modules", "styled-components"),
+   }
  }
```

### Usage with Lerna

One possible fix to get styled-components to run in a Lerna monorepo across packages, is to [hoist](https://github.com/lerna/lerna/blob/master/doc/hoist.md#disadvantages-with-hoisting) shared dependencies to the root of your monorepo file. Try running the bootstrap option with the --hoist flag.

```sh
lerna bootstrap --hoist
```

Alternatively, you can remove `styled-components` from your `package.json` file and hoist it manually to your top-level package.json file.

Example of a package.json file in a Lerna root folder

```json
{
  "name": "my-styled-monorepo",
  "devDependencies": {
    "lerna": "3.6.0"
  },
  "dependencies": {
    "styled-components": "3.4.5"
  },
  "scripts": {
    "bootstrap": "lerna bootstrap",
    "clean": "lerna clean",
    "start": "lerna run start",
    "build": "lerna run build"
  }
}
```

---

## How do I fix flickering text after server side rendering?

When using global styling APIs like [`createGlobalStyle`](/docs/api#createglobalstyle) or the former [`injectGlobal`](/docs/api#injectglobal), adding and removing certain styles from the DOM like `@font-face` definitions can cause momentary flickering of text on the page. This typically happens during the rehydration phase of server-side rendering. We're still tweaking how these behaviors work to avoid the issue long-term.

However, there is a CSS solution to the problem in the [`font-display` CSS rule](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display). By setting the rule to "fallback" mode, once a font has been loaded it will not be reloaded. This eliminates the flicker.

```css
@font-face {
  font-family: 'Foo';
  src: url('/path/to/foo.woff') format('woff');
  font-style: normal;
  font-weight: 400;
  font-display: fallback; /* <- this can be added to each @font-face definition */
}
```

---

## Why am I getting HTML attribute warnings?

The warning message below indicates that non-standard attributes are being attached to
HTML DOM elements such as `<div>` or `<a>`. If you are seeing this warning message, it is likely that you or a library you are using is attaching props as attributes to HTML DOM elements.

```
Warning: Received "true" for a non-boolean attribute
```

If you're seeing this warning you are probably passing `true` where `"true"` would be appropriate. It's likely that this comes from a `.attrs` property, or from a completely unrelated prop that you're passing to a `styled(Component)` component.

To learn more about how props are passed, see [this section](/docs/basics#passed-props 'Passing Props to styled-components').

For example:

```tsx
const Link = props => (
  <a {...props} className={props.className}>
    {props.text}
  </a>
)

const StyledComp = styled(Link)`
  color: ${props => (props.red ? 'red' : 'blue')};
`

<StyledComp text="Click" href="https://www.styled-components.com/" red />
```

This will render:

```html
<a text="Click" href="https://www.styled-components.com/" red="true" class="[generated class]">Click</a>
```

React will warn on non-standard attributes being attached such as "red" and "text", which are not valid HTML attributes for the `<a>` element.

To fix this, you can use transient props or destructure props:

### transient props (since 5.1)

You can use [transient props](https://styled-components.com/docs/api#transient-props) to fix this:

```tsx
const Link = ({ className, text, ...props }) => (
  <a {...props} className={className}>
    {text}
  </a>
)

const StyledComp = styled(Link)`
  color: ${props => (props.$red ? 'red' : 'blue')};
`

<StyledComp text="Click" href="https://www.styled-components.com/" $red />
```

### destructure props

If you use a version < 5.1 or if you can't use transient props, you can use argument destructuring to pull out those known styling props:

```tsx
const Link = ({ className, red, text, ...props }) => (
  <a {...props} className={className}>
    {text}
  </a>
)

const StyledComp = styled(Link)`
  color: ${props => (props.red ? 'red' : 'blue')};
`

<StyledComp text="Click" href="https://www.styled-components.com/" red />
```

This will render:

```html
<a href="https://www.styled-components.com/" class="[generated class]">Click</a>
```

When you use argument destructuring, any variables pulled out of the props object will not be included when spread-applying the remaining props (`...props`);

---

## I am a library author. Should I bundle `styled-components` with my library?

If you are a library author, we recommend that you should not bundle and ship `styled-components` module with your library. There are two steps that you need to do to achieve this:

- Marking `styled-components` as external in your package dependencies
- Removing `styled-components` from your library bundle

### Marking `styled-components` as external in your package dependencies

To do this, you will need to move it from `dependencies` to [`devDependencies`](https://docs.npmjs.com/files/package.json#devdependencies)
and include it in the [`peerDependencies`](https://docs.npmjs.com/files/package.json#peerdependencies) list in your `package.json` file:

```diff
  {
-   "dependencies" : {
+   "devDependencies" : {
      "styled-components": "^3.4.9"
    },
+   "peerDependencies" : {
+     "styled-components": ">= 3"
+   }
  }
```

Moving `styled-components` to `devDependencies` will guarantee that it wouldn't be installed along with your library (`npm install` or `yarn add` will ignore `devDependencies` when a library is installed).

Adding `styled-components` to `peerDependencies` will signal your library consumers that `styled-components` is not included with the library and they need to install it themselves.

Also, note that in the `peerDependencies` section the version string has been made a more permissive `>= 3`. This allows future versions of styled-components to work automatically and you can simply narrow the range with a patch update to your library if a breaking change is eventually added.

### Removing `styled-components` from your library bundle

If you are bundling your library before shipping it, make sure that you are not bundling `styled-components` along with it. Here are some examples of how to do this with some popular module bundling tools:

#### With Microbundle

If you are using [Microbundle](https://github.com/developit/microbundle), it will handle this step automatically. Microbundle treats every dependency in the `peerDependencies` list as external and excludes it from the build for you.

#### With Rollup.js

If you are using [Rollup.js](https://rollupjs.org), you should provide an [`external`](https://rollupjs.org/guide/en#big-list-of-options) option in your config:

```diff
  export default {
    entry: "my-awesome-library.js",
+   external: [
+     "styled-components"
+   ]
  }
```

Another approach is to use the [rollup-plugin-peer-deps-external](https://www.npmjs.com/package/rollup-plugin-peer-deps-external) plugin which will automatically add the `peerDependencies` in the `external` option array for you.

```diff
+ import peerDepsExternal from 'rollup-plugin-peer-deps-external';

  export default {
    entry: "my-awesome-library.js",
+   plugins: [
+    // Preferably set as first plugin.
+    peerDepsExternal(),
+   ]
  }
```

#### With Webpack

If you are using [Webpack](https://webpack.js.org), you should provide an [`externals`](https://webpack.js.org/configuration/externals/) option in your config:

```diff
  modules.export = {
    entry: "my-awesome-library.js",
+   externals: {
+     "styled-components": {
+       commonjs: "styled-components",
+       commonjs2: "styled-components",
+       amd: "styled-components",
+     },
+   },
  }
```

> You can find more useful information on how to bundle a library with Webpack at ["Authoring Libraries"](https://webpack.js.org/guides/author-libraries/) section of Webpack documentation.

---

## What do I need to do to migrate to v4?

This is a pretty big release with lots of changes both under the hood and at the API level. As the beta progresses, we will try to release codemods to make the items below simpler. Also, if you find any issues with the steps below, please [leave constructive feedback](https://github.com/styled-components/styled-components-website/issues/296)!

1. Upgrade to the latest styled-components:

```sh
npm install styled-components@^4.0.0
```

2. Make sure your application is using `react` >= 16.3; internally we are using the new `React.forwardRef` API and new context APIs if you wish to try and polyfill for older React version support

```sh
npm install react@^16.3 react-dom@^16.3
```

> If you are using `enzyme` or other dependencies like `react-test-renderer`, there may be more related upgrades to complete if you are coming from an old version of `react`.

3. If you are using the `.extend` API, switch your components to use `styled(StyledComponent)` instead.

A [codemod is available](https://github.com/styled-components/styled-components-codemods) to expedite this.

🚫

```tsx
import styled from 'styled-components'

const Component = styled.div`
  background: blue;
  color: red;
`

const ExtendedComponent = Component.extend`
  color: green;
`
```

✅

```tsx
import styled from 'styled-components'

const Component = styled.div`
  background: blue;
  color: red;
`

const ExtendedComponent = styled(Component)`
  color: green;
`
```

See the ["extending styles" documentation](/docs/basics#extending-styles) for more examples.

4. If you were using the `injectGlobal` API to add global styles to your page, use the new [`createGlobalStyle` helper component](/docs/api#createglobalstyle) instead.

A [codemod is available](https://github.com/styled-components/styled-components-codemods) to expedite this.

🚫

```tsx
import { injectGlobal } from 'styled-components'

injectGlobal`
  body {
    color: red;
  }
`
```

✅

```tsx
import { createGlobalStyle } from "styled-components"

const GlobalStyle = createGlobalStyle`
  body {
    color: red;
  }
`

// later in your app's render method
<React.Fragment>
  <Navigation />
  <OtherImportantTopLevelComponentStuff />
  <GlobalStyle />
</React.Fragment>
```

See the documentation for [`createGlobalStyle`](/docs/api#createglobalstyle) to see all the cool stuff you can do with it that wasn't possible before with `injectGlobal`!

5. If you were using the `innerRef` prop, change it to a normal `ref`.

🚫

```tsx
const Component = styled.div`
  background: blue;
  color: red;
`

// later in your render method
<Component innerRef={element => { this.myElement = element }}>Something something</Component>
```

✅

```tsx
const Component = styled.div`
  background: blue;
  color: red;
`

// later in your render method
<Component ref={element => { this.myElement = element }}>Something something</Component>
```

6. If you're using the `keyframes` component in a partial without the `css` helper, you'll need to use the helper now. In general, always use the css helper when composing styling partials to be interpolated into a styled component.

🚫

```tsx
import styled, { keyframes } from 'styled-components'

const animation = keyframes`
  0% {
    opacity: 0;
  }

  100 {
    opacity: 1;
  }
`

const animationRule = `
  ${animation} 1s infinite alternate
`

const Component = styled.div`
  animation: ${animationRule};
`
```

✅

```tsx
import styled, { css, keyframes } from 'styled-components'

const animation = keyframes`
  0% {
    opacity: 0;
  }

  100 {
    opacity: 1;
  }
`

const animationRule = css`
  ${animation} 1s infinite alternate;
`

const Component = styled.div`
  animation: ${animationRule};
`
```

7. If you're using `attrs({})` and some of the attributes you pass to it is a Function, it's recommended to switch to the new `attrs(props => ({}))` syntax instead for easier and more powerful composition.

🚫

```tsx
import styled from 'styled-components'

const Input = styled.input.attrs({
  type: props => props.inputType,
})`
  background: blue;
  color: red;
`
```

✅

```tsx
import styled from 'styled-components'

const Input = styled.input.attrs(props => ({
  type: props.inputType,
}))`
  background: blue;
  color: red;
`
```

8. If you're using TypeScript, the typings are now located in DefinitelyTyped:

```sh
npm install @types/styled-components
```

That's it! Aside from migrating, we also highly recommend reading up on the new [`"as" prop`](/docs/api#as-polymorphic-prop) which is intended to replace the [`withComponent API`](/docs/api#withcomponent) in the future.

---

## What do I need to do to migrate to v5?

Ready for this?

```sh
npm install styled-components@^5.0.0 react@^16.8 react-dom@^16.8 react-is@^16.8
```

If you're using React Native, you'll need at least v0.59 (the first version to support hooks.)

_That's it._ 💥

---

styled-components v5 does not introduce any breaking public API changes, and adds the following:

- Total rewrite of the core stylesheet engine, tuned for performance

- New hooks-based component model

- `StyleSheetManager` has new props:
  - `disableCSSOMInjection`
  - `disableVendorPrefixes`
  - `stylisPlugins`
    - try it with [`stylis-plugin-rtl`](https://www.npmjs.com/package/stylis-plugin-rtl) for your bidi needs!

> Note: The subfunction object-form `.attrs({ prop: props => {} })` syntax that was deprecated in v4 is removed in v5. Use function-form attrs instead `.attrs(props => ({}))` (you should have been seeing console warnings to make this update ahead of time.)

Check out the [official announcement post](https://medium.com/styled-components/389747abd987) for more information and to learn about what went into v5!

### For jest users

Update to jest-styled-components v7:

```sh
npm install jest-styled-components@^7.0.0
```

### Note regarding css `@import` and `createGlobalStyle`

At this time we do not recommend using `@import` within cGS due to some issues with how browsers process `@import` via the CSSOM APIs. Instead it's best to place these in your core `index.html` file (generated or static) within a typical `<style>` tag.

---

## What do I need to do to migrate to v6?

First, let's start by updating the necessary packages to their latest versions.

If you're using NPM:

```sh
npm install styled-components@^6.0.0 stylis@^4.0.0
npm uninstall @types/styled-components
```

If you're using Yarn:

```sh
yarn add styled-components@^6.0.0 stylis@^4.0.0
yarn remove @types/styled-components
```

As styled-components now provides its own types, there's no longer a need for community ones.

### TypeScript

Good news for TypeScript enthusiasts – styled-components is now natively written in TypeScript! Even if you haven't used TypeScript before, it's recommended for improving the reliability of your project as it can alert you when you're using an unknown prop or if a prop has a different value than expected.

However, if you don't use TypeScript in your project, don't worry! IDEs like VS Code will still pick up the types and provide hints as you write your code.

### `shouldForwardProp` is no longer provided by default

If you haven't migrated your styling to use [transient props (`$prefix`)](/docs/faqs#transient-props-since-5.1), you might notice React warnings about styling props getting through to the DOM in v6. To restore the v5 behavior, use `StyleSheetManager`:

```tsx
import isPropValid from '@emotion/is-prop-valid';
import { StyleSheetManager } from 'styled-components';

function MyApp() {
    return (
        <StyleSheetManager shouldForwardProp={shouldForwardProp}>
            {/* other providers or your application's JSX */}
        </StyleSheetManager>
    )
}

// This implements the default behavior from styled-components v5
function shouldForwardProp(propName, target) {
    if (typeof target === "string") {
        // For HTML elements, forward the prop if it is a valid HTML attribute
        return isPropValid(propName);
    }
    // For other elements, forward all props
    return true;
}
```

### Vendor prefixes are omitted by default

As the web and browsers have matured significantly by 2023, vendor prefixing is often unnecessary. Therefore, for the v6 release, we've decided to omit automatic prefixing by default to reduce the amount of CSS delivered to a page. If you prefer the v5 behavior, you can restore it via `StyleSheetManager`:

```tsx
import { StyleSheetManager } from 'styled-components';

function MyApp() {
    return (
        <StyleSheetManager enableVendorPrefixes>
            {/* other providers or your application's JSX */}
        </StyleSheetManager>
    )
}
```

To accommodate this change, the original `disableVendorPrefixes` prop was inverted to `enableVendorPrefixes`; if you have `disableVendorPrefixes` set, you can now remove it as it's the new default.

### Update stylis plugins

styled-components v6 uses the newer stylis v4; if you are providing `stylisPlugins` to `StyleSheetManager`, ensure the plugins are up-to-date. For instance, [`stylis-plugin-rtl`](https://www.npmjs.com/package/stylis-plugin-rtl) released a new version to support the updated stylis.

### Nested syntax handling

With the stylis v4 upgrade [came a change to how nested selectors are handled](https://github.com/thysultan/stylis/issues/323) which now correctly mirrors browser behavior. Specifically, pseudoselectors (e.g. `:before`) that do not start with `&` will not have the ampersand implicitly added anymore.

v5 behavior

```tsx
styled.div`
  :hover { color: red; }
`
// .[classname]:hover { color: red; }

styled.div`
  &:hover { color: red; }
`
// .[classname]:hover { color: red; }
```

v6 behavior

```tsx
styled.div`
  :hover { color: red; }
`
// .[classname] :hover { color: red; } (equivalent to .[classname] *:hover)

styled.div`
  &:hover { color: red; }
`
// .[classname]:hover { color: red; }
```

### Transient `$as` and `$forwardedAs` props have been dropped

To reduce confusion around application order, we've dropped the transient `$as` and `$forwardedAs` props. Please use the regular `as` and `forwardedAs` props instead.

### Dropped legacy `withComponent()` API

This change has been a long time coming. The `withComponent` API is no longer supported, so please use the `as` prop instead. You can specify `as` at definition time via `attrs` or at runtime:

```tsx
import styled from 'styled-components';

const Button = styled.button`
    background: blue;
    color: white;
`;

const ButtonLink = styled(Button).attrs({ as: 'a' })``;

// These are equivalent, but `ButtonLink` allows for attaching further styling if desired.
<Button as="a" href="https://styled-components.com">
<ButtonLink href="https://styled-components.com">
```

### Minimum Node support raised to v16+

In line with the [maintenance schedule](https://github.com/nodejs/release#release-schedule) for Node, we now support v16 as the oldest runtime that's still receiving security patches.

---

## Missing Declarations for `styled-components/native`?

If you're getting the error message:

```sh
Could not find a declaration file for module 'styled-components/native'
```

In a React Native project using TypeScript, it is because you need to add `@types/styled-components-react-native`.

---

## Can I nest rules?

Yes: nesting is a feature intentionally ported from Sass. Used sparingly it's a
great way to lighten your code by reducing the need to create explicit classes for every element.

It can also be used by parent components to define contextual constraints that aren't properly a concern of the affected children:

```react
const EqualDivider = styled.div`
  display: flex;
  margin: 0.5rem;
  padding: 1rem;
  background: papayawhip;
  ${props => props.$vertical && "flex-direction: column;"}

  > * {
    flex: 1;

    &:not(:first-child) {
      ${props => props.$vertical ? "margin-top" : "margin-left"}: 1rem;
    }
  }
`;

const Child = styled.div`
  padding: 0.25rem 0.5rem;
  background: #BF4F74;
`;

render(
  <div>
  <EqualDivider>
    <Child>First</Child>
    <Child>Second</Child>
    <Child>Third</Child>
  </EqualDivider>
  <EqualDivider $vertical>
    <Child>First</Child>
    <Child>Second</Child>
    <Child>Third</Child>
  </EqualDivider>
  </div>
);
```

It's also incredibly convenient to co-locate media queries, since we can see at a glance
exactly how the component will respond at any resolution.

```react
const ColorChanger = styled.section`
  background: papayawhip;
  color: #BF4F74;

  @media(min-width: 768px) {
    background: mediumseagreen;
    color: papayawhip;
  }
`;

render(
  <ColorChanger href="#">
    <h2>Hello world!</h2>
  </ColorChanger>
);
```

---

## How can I fix issues when using `npm link` or `yarn link`?

Local linking can be a useful tool to co-develop projects simultaneously. However, it creates chaotic situations with libraries that are meant to be used as singletons like react and styled-components since each of your local projects likely has a full set of development dependencies downloaded (and bundlers prefer local versions of dependencies by default.)

The solution is to add aliasing. Here's an example config for webpack:

```tsx
// const path = require('path');

{
  resolve: {
    alias: {
      // adjust this path as needed depending on where your webpack config is
      'styled-components': path.resolve('../node_modules/styled-components')
    }
  }
}
```

This ensures that for your build the same copy of the library will always be used, even across symlinked projects.

## Linking in an SSR SCENARIO.

If you are using the `collectStyles` function on a project with linked components you will end up in a complex scenario. Basically what's happening is that because of v4 new static context API different styled-component modules are now managing their own list of styled-components to render, from the host app it appears as though there's nothing to extract because no styled components have been created in that scope they were created from the linked package scope.

### How do I solve it?

One solution is to add an alias to the `styled-components` module path resolution to always point to the 'host' application. Hopefully there are a bunch of libraries to do that we will use for this example `module-alias`. At the very top of your SSR index file add:

```javascript
const path = require('path');
const moduleAlias = require('module-alias');

moduleAlias.addAlias('styled-components', path.join(__dirname, '../node_modules/styled-components'));
```

This will tell node to resolve all import/require's of styled-components to `__dirname, '../node_modules/styled-components'`

---

## How can I override inline styles?

Inline styles will always take precedence over external CSS, so you cannot override it by simply increasing specificity.

There is a neat trick however, which is to use the style `element-attr` CSS Selector in conjunction with `!important`:

```tsx
const MyStyledComponent = styled(InlineStyledComponent)`
  &[style] {
    font-size: 12px !important;
    color: blue !important;
  }
`
```

---

## How can I override styles with higher specificity?

The way to override styles with a high specificity is to simply increase the specificity of your own styles. This could be done using `!important`, but that's error prone and generally not a good idea.

We recommend the following technique:

```tsx
const MyStyledComponent = styled(AlreadyStyledComponent)`
  &&& {
    color: #BF4F74;
    font-weight: bold;
  }
`
```

Each `&` gets replaced with the generated class, so the injected CSS then looks like this:

```css
.MyStyledComponent-asdf123.MyStyledComponent-asdf123.MyStyledComponent-asdf123 {
  color: #BF4F74;
  font-weight: bold;
}
```

The repeated class bumps the specificity high enough to override the source order without being very tedious to write!

---

## Can I refer to other components?

Yes! This lets you adopt the "component selector" pattern, which lets components encapsulate the entirety of their styling: as with media queries, it lets components describe how they will behave when affected by external changes, without needing to refer to other parts of your codebase.

Here, our Icon component defines its response to its parent Link being hovered:

```react
const Link = styled.a`
  display: flex;
  align-items: center;
  padding: 5px 10px;
  background: papayawhip;
  color: #BF4F74;
`;

const Icon = styled.svg`
  transition: fill 0.25s;
  width: 48px;
  height: 48px;

  ${Link}:hover & {
    fill: rebeccapurple;
  }
`;

const Label = styled.span`
  display: flex;
  align-items: center;
  line-height: 1.2;

  &::before {
    content: "◀";
    margin: 0 10px;
  }
`;

render(
  <Link href="#">
    <Icon viewBox="0 0 20 20">
      <path d="M10 15h8c1 0 2-1 2-2V3c0-1-1-2-2-2H2C1 1 0 2 0 3v10c0 1 1 2 2 2h4v4l4-4zM5 7h2v2H5V7zm4 0h2v2H9V7zm4 0h2v2h-2V7z"/>
    </Icon>
    <Label>Hovering my parent changes my\u00A0style!</Label>
  </Link>
);
```

We could have nested the color-changing rule within our Link component, but then we'd have to consider both sets of rules to understand why Icon behaves as it does.

### Caveat

This behaviour is only supported within the context of _Styled_ Components:
attempting to mount `B` in the following example will fail because component
`A` is an instance of React.Component not a Styled Component.

```tsx
class A extends React.Component {
  render() {
    return <div />
  }
}

const B = styled.div`
  ${A} {
    color: red;
  }
`
```

The error thrown - `Cannot call a class as a function` - occurs because the
styled component is attempting to call the component as an interpolation function.

---

## Can I use CSS frameworks?

Integrating an existing CSS framework with styled-components is really easy! You can use its existing class names alongside your components.

For example, imagine you have an existing app with two classes you want to use again: `.small` and `.big`. If you want the class to always be attached to the component, you should use [the `attrs` method](/docs/api#attrs) to attach it. If you want to attach it only in some cases you can use the `className` props like you always have!

```react
// Using .attrs, we attach the .small class to every <Button />
const Button = styled.button.attrs(props => ({
  className: "small",
}))`
  background: black;
  color: white;
  cursor: pointer;
  margin: 1em;
  padding: 0.25em 1em;
  border: 2px solid black;
  border-radius: 3px;
`;

render(
  <div>
    <Button>Styled Components</Button>
    {/* Here we attach the class .big to this specific instance of the Button */}
    <Button className="big">The new way to style components!</Button>
  </div>
);
```

If the framework has a bunch of raw global CSS that needs to be included on the page, you can add it using the [`createGlobalStyle` API](/docs/api#createglobalstyle). This is also useful for things like CSS resets.

> Note that for styled-components v3 and below, the previous API for global styles was [`injectGlobal`](/docs/api#injectglobal).

---

## When to use attrs?

You can pass in attributes to styled components using [attrs](/docs/basics#attaching-additional-props), but it is not always sensible to do so.

The rule of thumb is to use `attrs` when you want every instance of a styled component to have that prop, and [pass props](/docs/basics#passed-props) directly when every instance needs a different one:

```tsx
const PasswordInput = styled.input.attrs(props => ({
  // Every <PasswordInput /> should be type="password"
  type: "password"
}))``

// This specific one is hidden, so let's set aria-hidden
<PasswordInput aria-hidden="true" />
```

The same goes for props that can be inferred based on the "mode" of another prop. In this case you can set a property on `attrs` to a function that computes that prop based on other props.

---

import { Content } from 'components/Layout'
import { AlignCenter, Badge, ExampleButton, SecondButton } from './components'
import NextPage from '../../components/NextPage'

export default ({ children }) => (
  <Content data-e2e-id="content">
    <AlignCenter>
      <a href="https://github.com/styled-components/styled-components">
        <Badge src="/api/proxy/stars.svg" alt="Stars on GitHub" />
      </a>
      <a href="https://www.npmjs.com/package/styled-components">
        <Badge src="/api/proxy/npm-v.svg" alt="Current version" />
      </a>
      <Badge src="/api/proxy/downloads.svg" alt="Monthly downloads" />
      <Badge src="/api/proxy/size.svg" alt="Gzipped size" />
      <a href="https://discord.gg/hfGUrbrxaU">
        <Badge alt="Discord" src="https://img.shields.io/discord/818449605409767454" />
      </a>
    </AlignCenter>
    {children}
  </Content>
)

# Getting started

## Installation

To download styled-components run:

```
npm install styled-components
```

That's all you need to do, you are now ready to use it in your app! (yep, no build step needed 👌)

> It's recommended (but not required) to also use the [styled-components Babel plugin](https://github.com/styled-components/babel-plugin-styled-components) if you can. It offers many benefits like more legible class names, server-side rendering compatibility, smaller bundles, and more.

## Your first styled component

Let's say you want to create a simple and reusable `<Button />` component that you can use throughout your application. There should be a normal version and a big and `primary` version for the important buttons. This is what it should look like when rendered: (this is a live example, click on them!)

<AlignCenter>
  <ExampleButton
    onClick={() => {
      alert('You clicked the normal button!')
    }}
  >
    Normal button
  </ExampleButton>
  <ExampleButton
    $primary
    onClick={() => {
      alert('You clicked the primary button!')
    }}
  >
    Primary button
  </ExampleButton>
</AlignCenter>

First, let's import styled-components and create a `styled.button`:

```tsx
import styled from 'styled-components'

const Button = styled.button``
```

This `Button` variable here is now a React component that you can use like any other React component! This unusual backtick syntax is a new JavaScript feature called a [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates).

You know how you can call functions with parenthesis? (`myFunc()`) Well, now you can also call functions with backticks! ([learn more about tagged template literals](/docs/advanced#tagged-template-literals))

If you render our lovely component now (just like any other component: `<Button />`) this is what you get:

<AlignCenter>
  <button>I'm a &lt;Button /&gt;!</button>
</AlignCenter>

It renders a button! That's not a very nice button though 😕 we can do better than this,
let's give it a bit of styling and tickle out the hidden beauty within!

```tsx
const Button = styled.button`
  background: transparent;
  border-radius: 3px;
  border: 2px solid #BF4F74;
  color: #BF4F74;
  margin: 0 1em;
  padding: 0.25em 1em;
`
```

<AlignCenter>
  <SecondButton>I'm a styled &lt;Button /&gt;</SecondButton>
</AlignCenter>

As you can see, styled-components lets you write actual CSS in your JavaScript. This means you can use all the features of CSS you use and love, including (but by far not limited to) media queries, all pseudo-selectors, nesting, etc.

The last step is that we need to define what a primary button looks like. To do that we also import `{ css }` from `styled-components` and interpolate a function into our template literal, which gets passed the props of our component:

```tsx
import styled, { css } from 'styled-components'

const Button = styled.button<{ $primary?: boolean; }>`
  background: transparent;
  border-radius: 3px;
  border: 2px solid #BF4F74;
  color: '#BF4F74';
  margin: 0 1em;
  padding: 0.25em 1em;

  ${props =>
    props.$primary &&
    css`
      background: '#BF4F74';
      color: white;
    `};
`
```

Here we're saying that when the `$primary` property is set we want to add some more `css` to our component, in this case change the background and color.

That's all, we're done! Take a look at our finished component:

```react
const Button = styled.button<{ $primary?: boolean; }>`
  background: transparent;
  border-radius: 3px;
  border: 2px solid #BF4F74;
  color: #BF4F74;
  margin: 0.5em 1em;
  padding: 0.25em 1em;

  ${props => props.$primary && css`
    background: #BF4F74;
    color: white;
  `}
`;

const Container = styled.div`
  text-align: center;
`

render(
  <Container>
    <Button>Normal Button</Button>
    <Button $primary>Primary Button</Button>
  </Container>
);
```

Nice 😍 That's a live updating editor too, so play around with it a bit to get a feel for what it's like to work with styled-components! Once you're ready, dive into the documentation to learn about all the cool things styled-components can do for you:

<NextPage title="Documentation" href="/docs" />

---

## Babel Macro | v4 | v5

> This functionality was removed in v6.1 due to lack of usage and unnecessary bloat for other consumers. [More info](https://github.com/styled-components/styled-components/issues/4064)

[Babel macros](https://babeljs.io/blog/2017/09/11/zero-config-with-babel-macros) are quickly gaining steam as a full-featured option to allow advanced code transpilation for zero-config projects like [create-react-app](https://github.com/facebook/create-react-app).

If your scaffold is set up with [`babel-plugin-macros`](https://github.com/kentcdodds/babel-plugin-macros), then simply use the new `styled-components/macro` import instead of `styled-components`:

```tsx
import styled, { createGlobalStyle } from 'styled-components/macro'

const Thing = styled.div`
  color: red;
`

const GlobalStyle = createGlobalStyle`
  body {
    color: 'white';
  }
`
```

The macro incorporates all the functionality of [our babel plugin](/docs/tooling#babel-plugin) while allowing the unejected tooling to handle the Babel part of the build process. Special thanks to [Luc Leray (@lucleray)](https://github.com/lucleray) for making this happen!

### EXPERIMENTAL Config

[`babel-plugin-macros`](https://github.com/kentcdodds/babel-plugin-macros) uses [`cosmiconfig`](https://www.npmjs.com/package/cosmiconfig) to read a `babel-plugin-macros` configuration which
can be located in any of the following files up the directories from the
importing file:

- `.babel-plugin-macrosrc`
- `.babel-plugin-macrosrc.json`
- `.babel-plugin-macrosrc.yaml`
- `.babel-plugin-macrosrc.yml`
- `.babel-plugin-macrosrc.js`
- `babel-plugin-macros.config.js`
- `babelMacros` in `package.json`

You can then specify the same options as [our babel plugin](/docs/tooling#babel-plugin) in `styledComponents` entry:

```tsx
// babel-plugin-macros.config.js
module.exports = {
  // ...
  // Other macros config
  styledComponents: {
    pure: true,
  },
}
```

For more information, see [EXPERIMENTAL config for babel-plugin-macros ](https://github.com/kentcdodds/babel-plugin-macros/blob/master/other/docs/author.md#config-experimental).

### Enforce macro imports

You may want to ensure that objects are consistently imported from the macro across your project. This can be achieved by using a [`no-restricted-imports`](https://eslint.org/docs/rules/no-restricted-imports) rule from ESLint:

```json
"no-restricted-imports": [
  "error",
  {
    "paths": [{
      "name": "styled-components",
      "message": "Please import from styled-components/macro."
    }],
    "patterns": [
      "!styled-components/macro"
    ]
  }
]
```

---

## Babel Plugin

This plugin adds support for server-side rendering, minification of styles, and a nicer debugging experience.

### Usage

Install the babel-plugin first:

```
npm install --save-dev babel-plugin-styled-components
```

Then add it to your babel configuration like so:

> ⚠️ The plugin call order in your `.babelrc` file matters. If you're using the env property in your babel configuration, then putting this plugin into the plugins array won't suffice. Instead it needs to be put into each env's plugins array to maintain it being executed first. See [this](https://github.com/styled-components/babel-plugin-styled-components/issues/78) for more information.

```tsx
{
  "plugins": ["babel-plugin-styled-components"]
}
```

### Server-side rendering

By adding a unique identifier to every styled component, this plugin avoids checksum mismatches due to different class generation on the client and on the server. If you do not use this plugin and try to server-side render styled-components React will complain with an HTML attribute mismatch warning during rehydration.

You can disable it if necessary with the `ssr` option:

```json
{
  "plugins": [
    [
      "babel-plugin-styled-components",
      {
        "ssr": false
      }
    ]
  ]
}
```

### Better debugging

This option enhances the attached CSS class name on each component with richer output to help identify your components in the DOM without React DevTools. In your page source you'll see: `<button class="Button-asdf123 asdf123" />` instead of just `<button class="asdf123" />`.

It also allows you to see the component's `displayName` in React DevTools. For example, consider writing a styled component that renders a `button` element, called `MyButton`. It will normally show up in DevTools as `styled.button`, but with the `displayName` option enabled, it has the name you gave it: `MyButton`.

This makes it easier to find your components and to figure out where they live in your app.

If you don't need this feature, you can disable it with the `displayName` option:

```json
{
  "plugins": [
    [
      "babel-plugin-styled-components",
      {
        "displayName": false
      }
    ]
  ]
}
```

#### Control the components `displayName`

By default, the `displayName` of a component will be prefixed with the filename in order to make the component name as unique as possible.

You can force the component `displayName` to be solely the component name by disabling the `fileName` option:

```json
{
  "plugins": [
    [
      "babel-plugin-styled-components",
      {
        "fileName": false
      }
    ]
  ]
}
```

One example you might want to do this, is testing components with enzyme. While you can always use `.find(ComponentName)` it's definitely possible to search component by its displayName with `.find("ComponentName")`. In the latter case you will need to disable the `fileName` option. If you do want this for testing only, make sure to add this only under your test environment.

#### Control which file names are meaningless

A common pattern is to put components in `Button/index.jsx` instead of `Button.jsx`. By default, if the `fileName` option is set to `true`, the plugin will generate the display name using the directory name (`<button class="Button-asdf123 asdf123" />`) instead of the file name (`<button class="index-asdf123 asdf123" />`), because the former provides more information.

The `meaninglessFileNames` option allows to customize the list of file names that are not relevant to the description of a styled component's functionality, and hence the directory name should be used instead:

```json
{
  "plugins": [
    [
      "babel-plugin-styled-components",
      {
        "meaninglessFileNames": ["index", "styles"]
      }
    ]
  ]
}
```

For example, adding `styles` to the list would enable you to store your styled components in a `Button/styles.js` file.

This option defaults to `["index"]`.

If either `fileName` or `displayName` are set to `false`, this option has no effect.

### Minification

Two types of minifications are performed by this plugin: one removes all whitespace & comments from your CSS and the other [transpiles tagged template literals](#template-string-transpilation), keeping valuable bytes out of your bundles.

If desired, you can disable this behavior via babel configuration:

```tsx
{
  "plugins": [
    ["babel-plugin-styled-components", {
      "minify": false,
      "transpileTemplateLiterals": false
    }]
  ]
}
```

### Dead Code Elimination

Due to how styled components are transpiled and constructed, by default minifiers cannot properly perform dead code elimination on them because they are assumed to have side effects. However, there is a feature that can be enabled to aid this process called "pure annotation".

```tsx
{
  "plugins": [
    ["babel-plugin-styled-components", {
      "pure": true
    }]
  ]
}
```

It utilizes a babel helper to tag each styled component and library helper with the `#__PURE__` JS comment that some minifiers use to overcome the aforementioned issue.

### Template String Transpilation

This plugin transpiles `styled-components` tagged template literals down to a smaller representation than what Babel normally creates.

_Wait, transpiling tagged template literals? Doesn't Babel do this natively?_ 🤔
With Babel, you're likely transpiling ES2015+ JavaScript to ES5-compliant code for older browser support. The most popularly recommended base Babel presets (`es2015` / `env` / `latest`) include the `babel-plugin-transform-es2015-template-literals` transform to make tagged template literals work in older browsers, but there is a caveat: output of that transform is quite verbose. It's done this way to meet specification requirements.

Here's an example of the transpiled code processed with `babel-preset-latest`:

```tsx
var _templateObject = _taggedTemplateLiteral(['width: 100%;'], ['width: 100%;'])
function _taggedTemplateLiteral(strings, raw) {
  return Object.freeze(Object.defineProperties(strings, { raw: { value: Object.freeze(raw) } }))
}
var Simple = _styledComponents2.default.div(_templateObject)
```

`styled-components` does not require full spec compatibility. Our Babel plugin will transpile template literals attached to styled components to a slightly different, smaller form which still works in older browsers but has a much smaller footprint.

Here's the previous example with the styled-components babel plugin on and the `{ transpileTemplateLiterals: true }` option:

```tsx
var Simple = _styledComponents2.default.div(['width: 100%;'])
```

The plugin is also smart enough to not modify tagged template literals belonging to other libraries and use cases:

````tsx
// Following will be converted:
styled.div``
keyframe``
css```some text` // But this will not be converted:

// Here the outer template literal will be converted
// because it's attached to the component factory,
// but the inner template literals will not be touched:
styled.div`
  color: ${light ? `white` : `black`};
`
````

You can disable this feature with the `transpileTemplateLiterals` option:

```json
{
  "plugins": [
    [
      "babel-plugin-styled-components",
      {
        "transpileTemplateLiterals": false
      }
    ]
  ]
}
```

Read more about [Tagged Template Literals](/docs/advanced#tagged-template-literals) in
our dedicated section explaining them.

### Namespace

The namespace will ensure that your class names will be unique; this setting is handy when you are working with micro frontends where class name collision can occur.

If desired, you can enable this behavior via babel configuration:

```tsx
{
  "plugins": [
    ["babel-plugin-styled-components", {
      "namespace": "my-app"
    }]
  ]
}
```

Here's an example of the transpiled code processed with `namespace` enabled:

```tsx
_styledComponents2.default.div.withConfig({
  displayName: 'code__before',
  componentId: 'my-app__sc-3rfj0a-1',
})(['color:blue;'])
```

> ⚠️ This feature is available from version **_1.11_**.

---

## Jest Integration

[Jest Styled Components](https://github.com/styled-components/jest-styled-components) is a set of utilities for testing Styled Components with [Jest](https://github.com/facebook/jest). This package improves the snapshot testing experience and provides a brand new matcher to make expectations on the style rules.

### Installation

```
npm install --save-dev jest-styled-components
```

### Snapshot Testing

When we are building a UI with Styled Components, we want to make sure the output doesn't change unexpectedly. Snapshot testing is an excellent way to test React components, and this package makes the experience even more delightful by adding the style to the snapshots.

Here's an example of a test:

```tsx
import React from 'react'
import styled from 'styled-components'
import renderer from 'react-test-renderer'
import 'jest-styled-components'

const Button = styled.button`
  color: red;
`

test('it works', () => {
  const tree = renderer.create(<Button />).toJSON()
  expect(tree).toMatchSnapshot()
})
```

And here's an example of the resulting snapshot:

```tsx
exports[`it works 1`] = `
.c0 {
  color: red;
}

<button
  className="c0"
/>
`
```

For a real world demo, check out
[this website's repository](https://github.com/styled-components/styled-components-website/tree/master/test).

### `toHaveStyleRule`

If we only want to check whether a particular style has been applied to an element, we can use the `toHaveStyleRule` matcher. This function takes two required parameters, a property (string) and a value (string or RegExp), and an optional object to search for rules nested within an at-rule or to add modifiers to the class selector.

```tsx
import React from 'react'
import styled from 'styled-components'
import renderer from 'react-test-renderer'
import 'jest-styled-components'

const Button = styled.button`
  color: red;
  @media (max-width: 640px) {
    &:hover {
      color: green;
    }
  }
`

test('it works', () => {
  const tree = renderer.create(<Button />).toJSON()
  expect(tree).toHaveStyleRule('color', 'red')
  expect(tree).toHaveStyleRule('color', 'green', {
    media: '(max-width: 640px)',
    modifier: ':hover',
  })
})
```

---

import StyledThemingExample from './styled-theming-example'

## Styled Theming

Create themes for your styled components using
[styled-theming](https://github.com/styled-components/styled-theming)

<StyledThemingExample />

Read the [introductory blog post](http://thejameskyle.com/styled-theming.html)

### Install

Install the babel-plugin first:

```
npm install --save styled-theming
```

### Example

```tsx
import React from 'react'
import styled, { ThemeProvider } from 'styled-components'
import theme from 'styled-theming'

const boxBackgroundColor = theme('mode', {
  light: '#fff',
  dark: '#000',
})

const Box = styled.div`
  background-color: ${boxBackgroundColor};
`

export default function App() {
  return (
    <ThemeProvider theme={{ mode: 'light' }}>
      <Box>Hello World</Box>
    </ThemeProvider>
  )
}
```

### API

#### `<ThemeProvider>`

See [styled-components docs](https://www.styled-components.com/docs/advanced#theming)

`<ThemeProvider>` is part of styled-components, but is required for
styled-theming.

```tsx
import { ThemeProvider } from 'styled-components'
```

`<ThemeProvider>` accepts a single prop `theme` which you should pass an
object with either strings or getter functions. For example:

```tsx
<ThemeProvider theme={{ mode: "dark", size: "large" }}>
<ThemeProvider theme={{ mode: modes => modes.dark, size: sizes => sizes.large }}>
```

You should generally set up a `<ThemeProvider>` at the root of your app:

```tsx
function App() {
  return (
    <ThemeProvider theme={...}>
      {/* rest of your app */}
    </ThemeProvider>
  );
}
```

#### `theme(name, values)`

Most of your theming will be done with this function.

`name` should match one of the keys in your `<ThemeProvider>` theme.

```tsx
;<ThemeProvider theme={{ whatever: '...' }} />
```

```tsx
theme("whatever", {...});
```

`values` should be an object where one of the keys will be selected by the
value provided to `<ThemeProvider>` theme.

```tsx
<ThemeProvider theme={{ mode: "light" }} />
<ThemeProvider theme={{ mode: "dark" }} />

theme("mode", {
  light: "...",
  dark: "...",
});
```

The values of this object can be any CSS value.

```tsx
theme("mode", {
  light: "#fff",
  dark: "#000",
});

theme("font", {
  sansSerif: '"Helvetica Neue", Helvetica, Arial, sans-serif',
  serif: 'Georgia, Times, "Times New Roman", serif',
  monoSpaced: "Consolas, monaco, monospace",
});
```

These values can also be functions that return CSS values.

```tsx
theme('mode', {
  light: props => props.theme.userProfileAccentColor.light,
  dark: props => props.theme.userProfileAccentColor.dark,
})
```

`theme` will create a function that you can use as a value in
styled-component's `styled` function.

```tsx
import styled from 'styled-components'
import theme from 'styled-theming'

const backgroundColor = theme('mode', {
  light: '#fff',
  dark: '#000',
})

const Box = styled.div`
  background-color: ${backgroundColor};
`
```

#### `theme.variants(name, prop, themes)`

It's often useful to create variants of the same component that are selected
via an additional prop.

To make this easier with theming, styled-theming provides a
`theme.variants` function.

```tsx
import styled from "styled-components";
import theme from "styled-theming";

const backgroundColor = theme.variants("mode", "variant", {
  default: { light: "gray", dark: "darkgray" },
  primary: { light: "blue", dark: "darkblue" },
  success: { light: "green", dark: "darkgreen" },
  warning: { light: "orange", dark: "darkorange" },
});

const Button = styled.button`
  background-color: ${backgroundColor};
`;

Button.propTypes = {
  variant: PropTypes.oneOf(["default", "primary", "success", "warning"])
};

Button.defaultProps = {
  variant: "default",
};

<Button />
<Button variant="primary" />
<Button variant="success" />
<Button variant="warning" />
```

---

## Stylelint

Lint your [styled components](https://github.com/styled-components/styled-components) with [stylelint](http://stylelint.io/)!

### Installation

#### For stylelint v15+ (recommended)

Configuring stylelint (v15+) for the first time? Follow these steps:

You need:

- `stylelint`
- The [stylelint-config-standard](https://github.com/stylelint/stylelint-config-standard), to extend the standard stylelint config
- The [postcss-styled-syntax](https://github.com/hudochenkov/postcss-styled-syntax), to parse your styled components and extract the CSS from them

```
npm install --save-dev \
  stylelint \
  stylelint-config-standard \
  postcss-styled-syntax
```

Add a `.stylelintrc` file to the root of your project:

```JSON
{
  "extends": [
    "stylelint-config-standard"
  ],
  "customSyntax": "postcss-styled-syntax"
}
```

#### For stylelint v14 and below

You need:

- `stylelint`
- The [stylelint-processor-styled-components](https://github.com/styled-components/stylelint-processor-styled-components), to extract styles from `styled-components`
- The [`stylelint-config-styled-components`](https://github.com/styled-components/stylelint-config-styled-components) to disable stylelint rules that clash with `styled-components`
- Your favorite `stylelint` config! (for example [`stylelint-config-recommended`](https://github.com/stylelint/stylelint-config-recommended))

> We recommend using Stylelint v9+ as this has added features that allow us to report correct line numbers on CSS syntax errors

```
npm install --save-dev \
  stylelint \
  stylelint-processor-styled-components \
  stylelint-config-styled-components \
  stylelint-config-recommended
```

Add a `.stylelintrc` file to the root of your project:

```JSON
{
  "processors": [
    "stylelint-processor-styled-components"
  ],
  "extends": [
    "stylelint-config-recommended",
    "stylelint-config-styled-components"
  ]
}
```

### Setup

You need to run `stylelint`. Add a `lint:css` script to your `package.json` which runs `stylelint` with a glob to all of your styled components:

```JSON
{
  "scripts": {
    "lint:css":"stylelint './src/**/*.js'"
  }
}
```

> The processor ignores javascript files that don't contain any `styled-components`, so don't worry about being too broad as long as you restrict it to javascript (or TypeScript).

Now you can lint your CSS by running the script! 🎉

```
npm run lint:css
```

> Stylelint `--fix` option works with same rules on version 15+.

#### Webpack

If you want to lint on build, rather than as a separate command, you can use the [`stylelint-custom-processor-loader`](https://github.com/emilgoldsmith/stylelint-custom-processor-loader) for webpack.

### `stylelint-config-styled-components`

When using this processor a couple of stylelint rules throw errors that cannot be prevented, like [`no-empty-source`](https://stylelint.io/user-guide/rules/no-empty-source) or [`no-missing-end-of-source-newline`](https://stylelint.io/user-guide/rules/no-missing-end-of-source-newline). There's also a couple rules which we need to enforce, like [`no-vendor-prefix` rules](https://stylelint.io/user-guide/rules/property-no-vendor-prefix). (`styled-components` automatically vendor prefixes your code, so you don't need to do it manually)

The [`stylelint-config-styled-components`](https://github.com/styled-components/stylelint-config-styled-components) will automatically disable rules that cause conflicts.

> You can override rules defined in shared configs in your custom `.stylelintrc`.

### Usage with other libraries

Some other libraries also implement the `styled.x` pattern with tagged template literals. This processor will lint the CSS in those tagged template literals too, as long as they use the `styled` keyword.

If you want to use the processor with another library but you also want to change the keyword (e.g. to write `cool.div` instead of `styled.div`) use the `moduleName` option:

```tsx
import cool from 'other-library';

const Button = cool.button`
  color: blue;
`;
```

```json
{
  "processors": [
    [
      "stylelint-processor-styled-components",
      {
        "moduleName": "other-library"
      }
    ]
  ]
}
```

> That double array is on purpose but only necessary if you set options, see the [processors configuration docs](https://stylelint.io/user-guide/configuration/#processors).

> We only officially support `styled-components`, but the hope is that other libraries can also benefit from the processor.

### Interpolation tagging (with `stylelint-processor-styled-components`)

Sometimes `stylelint` can throw an error (e.g. `CssSyntaxError`) even though nothing is wrong with your CSS. This is often due to an interpolation, more specifically the fact that the processor doesn't know what you're interpolating.

A simplified example:

```tsx
const something = 'background';

const Button = styled.div`
  ${something}: papayawhip;
`;
```

When you have interpolations in your styles the processor can't know what they are, so it makes a good guess and replaces them with a syntactically equivalent placeholder value. Since `stylelint` is not a code flow analysis tool this doesn't cover all edge cases and the processor will get it wrong every now and then.

Interpolation tagging allows you to tell the processor what an interpolation is in case it guesses wrong; it can then replace the interpolation with a syntactically correct value based on your tag.

For example:

```tsx
const something = 'background';

const Button = styled.div`
  // Tell the processor that "something" is a property
  ${/* sc-prop */ something}: papayawhip;
`;
```

Now the processor knows that the `something` interpolation is a property, and it can replace the interpolation with a property for linting.

To tag an interpolation add a comment at either the start or the end of the interpolation. (`${/* sc-tag */ foo}` or `${bar /* sc-tag */}`) Tags start with `sc-` and, if specified, a tag overrides the processors guess about what the interpolation is.

#### Tags

The full list of supported tags:

- `sc-block`
- `sc-selector`
- `sc-declaration`
- `sc-property`
- `sc-value`

> If you are in doubt of the vocabulary you can refer to [this CSS vocabulary list](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference) with examples.

For example, when you interpolate another styled component, what you really interpolate is its unique selector. Since the processor doesn't know that, you can tell it to replace it with a selector when linting:

```tsx
const Wrapper = styled.div`
  ${/* sc-selector */ Button} {
    color: red;
  }
`;
```

You can also use shorthand tags to avoid cluttering the code. For example:

```tsx
const Wrapper = styled.div`
  ${/* sc-sel */ Button} {
    color: red;
  }
`;
```

##### `sc-custom`

**`sc-custom` is meant to be used as a last resort escape hatch. Prefer to use the standard tags if possible!**

On top of the above standard tags the processor also has the `sc-custom` tag to allow you to cover more unique and uncommon edge cases. With the `sc-custom` tag you can decide yourself what the placeholder value will be.

For example:

```tsx
// Switch between left and right based on language settings passed through via the theme
const rtlSwitch = (props) => (props.theme.dir === 'rtl' ? 'left' : 'right');

const Button = styled.button`
  background: green;
  // Tell the processor to replace the interpolation with "left"
  // when linting
  margin-${/* sc-custom "left" */ rtlSwitch}: 12.5px;
`;
```

### Syntax notes

#### Turning rules off from within your JS/CSS

Turn off rules with `stylelint-disable` comments (see the [stylelint documentation](https://stylelint.io/user-guide/configuration/#turning-rules-off-from-within-your-css) for all allowed syntax) both inside and outside of the tagged template literals.

```tsx
import React from 'react';
import styled from 'styled-components';

// Disable stylelint from within the tagged template literal
const Wrapper = styled.div`
  /* stylelint-disable */
  background-color: 123;
`;

// Or from the JavaScript around the tagged template literal
/* stylelint-disable */
const Wrapper = styled.div`
  background-color: 123;
`;
```

#### Template literal style and indentation

In order to have stylelint correctly apply indentation rules the processor needs to do a bit of opinionated preprocessing on the styles, which results in us only officially supporting one indentation style. (the supported style is the "default" one as shown in all the documentation)

The important thing is that you put the closing backtick on the base level of indentation as follows:

**Right**

```tsx
if (condition) {
  const Button = styled.button`
    color: red;
  `;
}
```

**Wrong**

```tsx
if (condition) {
  const Button = styled.button`
    color: red;
`
}
```

```tsx
if (condition) {
  const Button = styled.button`
    color: red;`
}
```

It may be that other tagged template literal styles are coincidentally supported, but no issues will be handled regarding indentation unless the above style was used.

---

## SWC Plugin

This plugin adds support for server-side rendering, minification of styles, and better debugging experience when using styled-components with the SWC compiler.

### Usage

First, install the `@swc/plugin-styled-components` and `@swc/core` packages:

```bash
npm install --save-dev @swc/plugin-styled-components @swc/core
```

Then, add the plugin to your `.swcrc` configuration file:

```json
{
  "jsc": {
    "experimental": {
      "plugins": [
        [
          "@swc/plugin-styled-components",
          {
            "displayName": true,
            "ssr": true
          }
        ]
      ]
    }
  }
}
```

### Options

* `displayName`:
  * Description: Enhances the attached CSS class name on each component with richer output to help identify your components in the DOM without React DevTools. It also allows you to see the component's `displayName` in React DevTools.
  * Type: Boolean
  * Default: `true`
  * Values: `true` or `false`
* `ssr`:
  * Description: Adds a unique identifier to every styled component to avoid checksum mismatches due to different class generation on the client and on the server. Helps in server-side rendering (SSR).
  * Type: Boolean
  * Default: `true`
  * Values: `true` or `false`
* `fileName`:
  * Description: Controls whether the `displayName` of a component will be prefixed with the filename or solely the component name.
  * Type: Boolean
  * Default: `true`
  * Values: `true` or `false`
* `meaninglessFileNames`:
  * Description: Allows customizing the list of file names that are not relevant to the description of a styled component's functionality. Uses directory names instead.
  * Type: Array of strings
  * Default: `["index", "styles"]`
  * Values: Any array of strings representing meaningless file names.
* `minify`:
  * Description: Minifies your CSS by removing all whitespace and comments. Also transpiles tagged template literals to a smaller representation.
  * Type: Boolean
  * Default: `true`
  * Values: `true` or `false`
* `transpileTemplateLiterals`:
  * Description: Transpiles `styled-components` tagged template literals to a smaller representation. Helps reduce bundle size.
  * Type: Boolean
  * Default: `true`
  * Values: `true` or `false`
* `pure`:
  * Description: Enables a feature called "pure annotation" to aid dead code elimination process on styled components.
  * Type: Boolean
  * Default: `false`
  * Values: `true` or `false`
* `namespace`:
  * Description: Ensures that your class names will be unique, useful when working with micro-frontends where class name collisions can occur.
  * Type: String
  * Default: `undefined`
  * Values: Any string representing the desired namespace.

### Server-side rendering

By adding a unique identifier to every styled component, this plugin avoids checksum mismatches due to different class generation on the client and on the server. If you don't use this plugin and try to server-side render styled components, React will complain with an HTML attribute mismatch warning during rehydration.

You can disable this feature by setting the `ssr` option to `false`:

```json
{
  "jsc": {
    "experimental": {
      "plugins": [
        [
          "@swc/plugin-styled-components",
          {
            "ssr": false
          }
        ]
      ]
    }
  }
}
```

### Better Debugging

This option enhances the attached CSS class name on each component with richer output to help identify your components in the DOM without React DevTools. It also allows you to see the component's `displayName` in `React` DevTools.

If you don't need this feature, you can disable it by setting the `displayName` option to `false`:

```json
{
  "jsc": {
    "experimental": {
      "plugins": [
        [
          "@swc/plugin-styled-components",
          {
            "displayName": false
          }
        ]
      ]
    }
  }
}
```

#### Control the components `displayName`

By default, the `displayName` of a component will be prefixed with the filename in order to make the component name as unique as possible.

You can force the component `displayName` to be solely the component name by disabling the `fileName` option:

```json
{
 "jsc": {
   "experimental": {
     "plugins": [
       [
         "@swc/plugin-styled-components",
         {
           "fileName": false
         }
       ]
     ]
   }
 }
}
```

#### Control which file names are meaningless

A common pattern is to put components in `Button/index.jsx` instead of `Button.jsx`. By default, if the `fileName` option is set to `true`, the plugin will generate the `displayName` using the directory name (`<button class="Button-asdf123 asdf123" />`) instead of the file name (`<button class="index-asdf123 asdf123" />`), because the former provides more information.

The `meaninglessFileNames` option allows you to customize the list of file names that are not relevant to the description of a styled component's functionality, and hence the directory name should be used instead:

```json
{
 "jsc": {
   "experimental": {
     "plugins": [
       [
         "@swc/plugin-styled-components",
         {
           "meaninglessFileNames": ["index", "styles"]
         }
       ]
     ]
   }
 }
}
```

### Minification

This plugin minifies your CSS by removing all whitespace and comments. It also transpiles tagged template literals to a smaller representation, keeping valuable bytes out of your bundles.

If desired, you can disable this behavior by setting the `minify` option to `false`:

```json
{
 "jsc": {
   "experimental": {
     "plugins": [
       [
         "@swc/plugin-styled-components",
         {
           "minify": false,
           "transpileTemplateLiterals": false
         }
       ]
     ]
   }
 }
}
```

### Dead Code Elimination

Due to how styled components are transpiled and constructed, by default, minifiers cannot properly perform dead code elimination on them because they are assumed to have side effects. However, there is a feature that can be enabled to aid this process called "pure annotation".

```json
{
 "jsc": {
   "experimental": {
     "plugins": [
       [
         "@swc/plugin-styled-components",
         {
           "pure": true
         }
       ]
     ]
   }
 }
}
```

### Template String Transpilation

Similar to the Babel plugin, this plugin transpiles `styled-components` tagged template literals to a smaller representation than what SWC normally creates. This helps reduce the bundle size.

You can disable this feature by setting the `transpileTemplateLiterals` option to `false`:

```json
{
 "jsc": {
   "experimental": {
     "plugins": [
       [
         "@swc/plugin-styled-components",
         {
           "transpileTemplateLiterals": false
         }
       ]
     ]
   }
 }
}
```

### Namespace

The `namespace` option ensures that your class names will be unique, which is handy when working with micro-frontends where class name collisions can occur.

To enable this behavior, set the `namespace` option in your configuration:

```json
{
 "jsc": {
   "experimental": {
     "plugins": [
       [
         "@swc/plugin-styled-components",
         {
           "namespace": "my-app"
         }
       ]
     ]
   }
 }
}
```

---

## Syntax Highlighting

The one thing you used to lose when writing CSS in template literals is syntax highlighting. We're working hard on making proper syntax highlighting happening in all editors. We currently have support for Atom, Visual Studio Code, WebStorm, and soon Sublime Text.

This is what it looks like when properly highlighted:

<img alt="Syntax highlighted styled component" src="/syntax-highlight-example.jpg" height="250px" />

### Atom

[**@gandm**](https://github.com/gandm), the creator of `language-babel`, has added support for `styled-components` in Atom!

To get proper syntax highlighting, all you have to do is install and use the `language-babel` package for your JavaScript files!

### Sublime Text

A [PR](https://github.com/babel/babel-sublime/pull/289) by [@garetmckinley](https://github.com/garetmckinley) has been merged into `babel-sublime` but has not been released to Package Control. It is, however, available to install directly from GitHub as described in [this issue](https://github.com/babel/babel-sublime/issues/333).

Another option is [Naomi](https://github.com/borela/naomi) by [Alexandre Borela](https://github.com/borela), a collection of syntax highlighting definitions for Sublime Text 3 which supports `styled-components` out-of-the-box.

### Visual Studio Code

[**@gandm**](https://github.com/gandm)'s language-babel has been ported to VSCode under the name [Babel JavaScript](https://marketplace.visualstudio.com/items?itemName=mgmcdermott.vscode-language-babel) by [Michael McDermott](https://twitter.com/michaelgmcd). It provides the same all-in-one solution for Babel syntax highlighting with styled-components included.

If you would like to keep your current JavaScript syntax highlighting, you can use the [vscode-styled-components](https://github.com/styled-components/vscode-styled-components) extension to provide styled-components syntax highlighting inside your Javascript files. You can install it as usual from the [Marketplace](https://marketplace.visualstudio.com/items?itemName=styled-components.vscode-styled-components).

### NeoVim
If you're using NeoVim with TreeSitter, you can add `styled` into your config's `ensure_installed` table:
```lua
require'nvim-treesitter.configs'.setup {
  ensure_installed = { ..., "styled" },
  highlight = {
    enable = true,
  },
}
```

### WebStorm, IntelliJ IDEA, PhpStorm, PyCharm, and RubyMine

The [`webstorm-styled-components`](https://github.com/styled-components/webstorm-styled-components) plugin adds code completion and highlighting for CSS properties and values in the template strings. And it also provides code completion and navigation for JavaScript symbols in the interpolations. You can install it from the IDE: go to `Preferences | Plugins` and search for `Styled Components`.

### Other Editors

We could use your help to get syntax highlighting support to other editors! All these syntax highlighting were built by the Styled Components community so if you want to start working on syntax highlighting for your editor, we would love to see it.

---

## TypeScript Plugin

[`typescript-plugin-styled-components`](https://github.com/Igorbek/typescript-plugin-styled-components) is a plugin for TypeScript that gives you a nicer debugging experience.

> ⚠️ TypeScript does not allow to use any plugin or transformer directly from the command line compiler `tsc`. So the plugin only works with build toolchains such as `webpack` with one of TypeScript loaders. There's [an open issue](https://github.com/Microsoft/TypeScript/issues/16607) to bring plugins to tsc though if you want to upvote it!

Please refer to [the project's GitHub repo](https://github.com/Igorbek/typescript-plugin-styled-components) for documentation.