API Reference



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

1. component / tagnameEither a valid react component or a tagname like 'div'.

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

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


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.

RuleAny CSS rules (string)
InterpolationThis 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.

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.


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


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:

Prop ValueThese can be of any type, except functions. They'll stay static and will be merged into the existing component props.
Prop FactoryA 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.

Returns another StyledComponent.

Learn more about this constructor in the Attaching Additional Props section.


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.

1. component / tagnameEither a valid react component or a tagname like `'div'`.

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


As of styled-components v4 the withComponent API is now a candidate for deprecation. In all likelihood, you probably want to use the new "as" prop to simply switch what element/component being rendered since the withComponent API is destructive toward styles if the lowest-wrapped component is a StyledComponent.

"as" polymorphic prop

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.

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

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

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.


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.

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.


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.

themeAn object that will be injected as theme into all interpolations in styled components beneath the provider.

css prop

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.

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

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

You can use the 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:

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:

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



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.

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

Since the GlobalStyle component is a StyledComponent, that means it also has access to theming from the <ThemeProvider> component if provided.


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.

1. TaggedTemplateLiteralA tagged template literal with your CSS and interpolations.

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

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


A helper method to create keyframes for animations.

1. TaggedTemplateLiteralA tagged template literal with your keyframes inside.

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.

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

You can learn more about using animations with styled-components in the Animations section.


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.

disableCSSOMInjection (v5+)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.
disableVendorPrefixes (v5+)Opts the given subtree out of adding legacy CSS properties for rendered components.
sheetThar be dragons ahead. Create and provide your own StyleSheet if necessary for advanced SSR scenarios.
stylisPlugins (v5+)An array of plugins to be run by stylis during compilation. Check out what's available on npm.
targetThar be dragons ahead. Provide an alternate DOM node to inject styles info.

For example if your app runs only in modern browsers, you may want to disable vendor prefixing for your styles:

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


A utility to help identify styled components.

1. FunctionAny function expected to possibly be a styled component or React component wrapped in a styled component

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:


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.

1. ComponentAny valid React component that can handle a theme prop.

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


All styled components automatically receive the theme as a prop, so this is only necessary if you wish to access the theme for other reasons.


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


All styled components automatically receive the theme as a prop, so this is only necessary if you wish to access the theme for other reasons.


This is the "consumer" component created by React.createContext as the companion component to ThemeProvider. It uses the render prop pattern to allow for dynamic access to the theme during rendering.

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


All styled components automatically receive the theme as a prop, so this is only necessary if you wish to access the theme for other reasons.

Test Utilities


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


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


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

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!

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


styled-components has first-class Flow support to help you find typing errors while using our public API.

To use Flow with the public api of styled-components we recommend that you use the library definition in flow-typed. To install it you can use the flow-typed cli or download it manually from the git repository and store it in a flow-typed/ folder in the same directory with your flowconfig.

Installing the definitions


If you are on npm >= 5.2 you could simply use npx

Ignore styled-components source

You should add the following lines to your .flowconfig, if you run into Flow errors, coming from the styled-components package in your node_modules directory.


styled-components has community-organized TypeScript definitions on DefinitelyTyped which powers the editing experience in IDEs and can provide types for TypeScript projects. To install them, run:

React Native only: If your tsconfig assigns types then you will need to add "styled-components-react-native" there. For example:


Now that Babel 7 is out and the TypeScript preset is available, it's now possible to use the styled-components babel plugin in conjunction with TypeScript.

Before you can effectively start to use TypeScript you will have to do a little bit of configuration.

Create a declarations file

TypeScript definitions for styled-components can be extended by using declaration merging 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.

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.


Styling components

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

Using custom props

If you are adapting the styles 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):

Note: if you style a standard tag (like <h1> in above example), styled-components will not pass the custom props (to avoid the Unknown Prop Warning).

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

If the customColor property should not be transferred to the Header component, you can leverage transient props, by prefixing it with a dollar sign ($):

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

Or using shouldForwardProp:

Caveat with className

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

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:

Previous APIs

[Deprecated] .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.

1. TaggedTemplateLiteralA tagged template literal with your CSS and interpolations.

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

[Deprecated] 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.

1. TaggedTemplateLiteralA tagged template literal with your global styles inside.

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.

[Deprecated] "innerRef" prop


The "innerRef" prop was removed in styled-components v4 in favor of the React 16 forwardRef API. 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.

Continue on the next page