Primary

styled

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

Arguments	Description
component / tagname	Either a valid react component or a tagname like 'div'.

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

// 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>
  </>
)
// 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>
  </>
)
I'm purple.
I'm red.

You can see this method being introduced in the Getting started section.

Additional HTML & SVG elements

v6.3.0+

In addition to standard HTML elements like styled.div and styled.button, the following element helpers were added in v6.3.0:

HTML elements: styled.search, styled.slot, styled.template

SVG elements: styled.clipPath, styled.linearGradient, styled.radialGradient, styled.textPath, styled.switch, styled.symbol, styled.use, and all SVG filter primitives (styled.feBlend, styled.feColorMatrix, styled.feGaussianBlur, styled.feComposite, styled.feMerge, styled.feMergeNode, styled.feOffset, styled.feFlood, styled.feTurbulence, styled.feDisplacementMap, styled.feDistantLight, styled.fePointLight, styled.feSpotLight, styled.feImage, styled.feMorphology, styled.feSpecularLighting, styled.feDiffuseLighting, styled.feConvolveMatrix, styled.feTile, styled.feDropShadow, styled.feFuncR, styled.feFuncG, styled.feFuncB, styled.feFuncA).

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 section.

Inputs	Description
Rule	Any CSS rules (string)
Interpolation	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.

Read more about how to adapt styling based on props in the 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 for more information on this.

// 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>
)
// 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>
)
✨ Magic

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.

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)

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. Pass either an object or a factory function; the returned attrs are merged into the component's props. The attrs argument accepts the following shapes:

Values	Description
Prop Value	These can be of any type, except functions. They'll stay static and will be merged into the existing component props.
Prop Factory	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. The factory accepts an optional second argument, ast, for reading style declarations or theme tokens. See Bridging styles into props.

Returns another StyledComponent.

// 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" />
  </>
)
// 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 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.

// import styled from "styled-components";


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


render(
  <Component
    as="button"
    onClick={() => alert('It works!')}
  >
    Hello World!
  </Component>
)
// import styled from "styled-components";

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

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

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.

In v7, TypeScript editor completion follows the intrinsic target named by as. For example, <Component as="video" ...> offers video attributes such as controls, muted, loop, and poster.

"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.

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


render(
  <Comp $draggable="red" draggable="true">
    Drag me!
  </Comp>
);
const Comp = styled.div`
  color: ${props =>
    props.$draggable || 'black'};
`;

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

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.

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>
);
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>
);
Drag Me!

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.

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.

Props	Description
theme	An object (or function returning an object) that will be injected as theme into all interpolations in styled components beneath the provider.

Simple usage:

// 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>
)
// 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>
)
I'm mediumseagreen!

Adding to or replacing an outer theme using nested ThemeProvider:

// 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>
)
// 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>
)
I'm mediumseagreen with a white background!
I'm mediumseagreen with a black background!

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.

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

The Babel plugin handles the styled-components import automatically; you don't need to add it yourself.

Usage with TypeScript

For v6+, you do not need to install @types/styled-components. You can directly import the CSSProp in your project like this:

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


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

For older versions, install @types/styled-components and add the following import once in your project:

import {} from 'styled-components/cssprop'

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

Helpers

createGlobalStyle

v4web-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.

Arguments	Description
TaggedTemplateLiteral	A tagged template literal with your CSS and interpolations.

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".

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 if provided.

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


const GlobalStyle = createGlobalStyle<{ $whiteColor?: boolean; }>`
  body {