Annotating React Styled Components with TypeScript

Styled components redefine how we apply CSS styles to React components. Unlike the traditional approach of manually assigning CSS classes (from an imported CSS file) to elements within a component, CSS-in-JS libraries like 

 provide primitives for locally scoping CSS styles to a component with unique, auto-generated CSS classes.

 component composed of several styled React components. Each of 

's helper methods corresponds to a specific DOM node:

import styled from "styled-components";

const S = {
  Card: styled.div`
    width: 18rem;
    border: 1px solid #cbcdcf;
    border-radius: 0.25rem;
    display: flex;
    flex-direction: column;
    position: relative;
  `,
  CardImage: styled.img`
    border-top-left-radius: 0.25rem;
    border-top-right-radius: 0.25rem;
    width: 100%;
  `,
  CardBody: styled.div`
    padding: 1rem;
  `,
  CardTitle: styled.h4`
    font-size: 1.5rem;
    margin: 0 0 1rem;
  `,
  CardText: styled.p`
    font-size: 1.125rem;
    margin: 1rem 0;
    display: -webkit-box;
    -webkit-line-clamp: 5;
    -webkit-box-orient: vertical;
    overflow: hidden;
  `,
  CardLink: styled.a`
    font-size: 1.25rem;
    display: inline-block;
    color: #fff;
    background-color: #0c6dfc;
    border-color: #0c6dfc;
    border-radius: 0.25rem;
    padding: 0.5rem 0.875rem;
    cursor: pointer;
    text-align: center;
    text-decoration: none;
    transition: background-color 0.2s ease-in, border-color 0.2s ease-in;

    &:hover,
    &:focus {
      background-color: #0a5dd6;
      border-color: #0957c9;
    }
  `,
};

const Card = ({ title, text, url, imageUrl }) => (
  <S.Card>
    <S.CardImage src={imageUrl} alt={title} />
    <S.CardBody>
      <S.CardTitle>{title}</S.CardTitle>
      <S.CardText>{text}</S.CardText>
      <S.CardLink href={url}>See More</S.CardLink>
    </S.CardBody>
  </S.Card>
);

export default Card;

 component's styles, structure and logic can all be found within a single file. 

 comes up with a unique class name for each set of CSS rules, feeds the CSS to a CSS preprocessor (Stylis), places the compiled CSS within a 

 tag into the page and adds the CSS classes to the elements.

By tightly coupling components to their styles, we can easily maintain CSS in large React applications. If we need to edit anything about a component, whether it be its color or how it responds to user input, then we can visit one file, which keeps everything related to the component colocated, to make the necessary changes. Unique class names prevent naming collisions with existing class names.

, come with TypeScript definitions. When pairing styled components with TypeScript, our React application gains all the benefits of a statically typed language while also ensuring component styles remain well-organized. As we write our styled components, our IDE can warn us of any incorrect arguments passed to any of the helper methods, detect typos, perform autocompletion, highlight missing props, etc.

Below, I'm going to show you how to annotate React styled components with TypeScript.

To get started, scaffold a new React application with the Create React App and TypeScript boilerplate template.

$ npx create-react-app <project-name> --template typescript

$ npm install --save styled-components
$ npm install --save-dev @types/styled-components

, which contains the React application's components.

Within this new directory, create a new file 

 component's source code (from above) into this file.

For React Native projects, you would need to install an additional set of type definitions:

$ npm install --save-dev @types/styled-components-react-native

{
  "compilerOptions": {
    "types": ["styled-components-react-native"]
  }
}

Suppose we wanted to annotate the example 

Annotating a React functional component requires:

import { FC } from "react";
import styled from "styled-components";

// ...

interface CardProps {
  title: string;
  text: string;
  url: string;
  imageUrl: string;
}

const Card: FC<CardProps> = ({ title, text, url, imageUrl }) => (
  <S.Card>
    <S.CardImage src={imageUrl} alt={title} />
    <S.CardBody>
      <S.CardTitle>{title}</S.CardTitle>
      <S.CardText>{text}</S.CardText>
      <S.CardLink href={url}>See More</S.CardLink>
    </S.CardBody>
  </S.Card>
);

export default Card;

 component's styles within a parent component, then we need the 

 prop. By default, all properties are required, but those marked with a question mark are considered optional.

import { FC } from "react";
import styled from "styled-components";

// ...

interface CardProps {
  className?: string;
  title: string;
  text: string;
  url: string;
  imageUrl: string;
}

const Card: FC<CardProps> = ({ className, title, text, url, imageUrl }) => (
  <S.Card className={className}>
    <S.CardImage src={imageUrl} alt={title} />
    <S.CardBody>
      <S.CardTitle>{title}</S.CardTitle>
      <S.CardText>{text}</S.CardText>
      <S.CardLink href={url}>See More</S.CardLink>
    </S.CardBody>
  </S.Card>
);

export default Card;

 component can be modified from a parent component.

import styled from "styled-components";
import Card from "./components/Card";

const StyledApp = styled.div`
  display: grid;
  grid-column-gap: 1rem;
  grid-template-columns: repeat(3, 18rem);
`;

const RedCard = styled(Card)`
  background-color: red;
`;

const App = () => (
  <StyledApp>
    <Card
      title="Domestic Cat"
      text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
      url="https://en.wikipedia.org/wiki/Cat"
      imageUrl="https://placekitten.com/408/287"
    />
    <RedCard
      title="Domestic Cat"
      text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
      url="https://en.wikipedia.org/wiki/Cat"
      imageUrl="https://placekitten.com/408/287"
    />
  </StyledApp>
);

export default App;

Suppose a styled component's inner DOM element must be accessed by a parent component. To forward a ref to a styled component, we must pass the styled component to the 

 function, which forwards the ref to an inner DOM element that the styled component renders.

import { forwardRef } from "react";

// ...

const Card = forwardRef(({ className, title, text, url, imageUrl }, ref) => (
  <S.Card className={className} ref={ref}>
    <S.CardImage src={imageUrl} alt={title} />
    <S.CardBody>
      <S.CardTitle>{title}</S.CardTitle>
      <S.CardText>{text}</S.CardText>
      <S.CardLink href={url}>See More</S.CardLink>
    </S.CardBody>
  </S.Card>
));

export default Card;

Annotating a styled component that receives a forwarded ref involves two steps:

import { ComponentPropsWithoutRef, forwardRef } from "react";
import styled from "styled-components";

// ...

interface CardProps extends ComponentPropsWithoutRef<"div"> {
  className?: string;
  title: string;
  text: string;
  url: string;
  imageUrl: string;
}

const Card = forwardRef<HTMLDivElement, CardProps>(
  ({ className, title, text, url, imageUrl }, ref) => (
    <S.Card className={className} ref={ref}>
      <S.CardImage src={imageUrl} alt={title} />
      <S.CardBody>
        <S.CardTitle>{title}</S.CardTitle>
        <S.CardText>{text}</S.CardText>
        <S.CardLink href={url}>See More</S.CardLink>
      </S.CardBody>
    </S.Card>
  )
);

export default Card;

 element and access it whenever it needs to register event listeners on the component, read/edit DOM properties, etc.

import { useEffect, useRef } from "react";
import styled from "styled-components";
import Card from "./components/Card";

// ...

const App = () => {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    console.log(ref.current);
  }, []);

  return (
    <StyledApp>
      <Card
        ref={ref}
        title="Domestic Cat"
        text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
        url="https://en.wikipedia.org/wiki/Cat"
        imageUrl="https://placekitten.com/408/287"
      />
      <RedCard
        title="Domestic Cat"
        text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
        url="https://en.wikipedia.org/wiki/Cat"
        imageUrl="https://placekitten.com/408/287"
      />
    </StyledApp>
  );
};

export default App;

Annotating a Custom Theme and Adapted Styles Based on Props

 lets you easily customize your React application's theme via the 

 wrapper component, which uses the context API to allow all children components underneath it to have access to the current theme.

import { render } from "react-dom";
import { ThemeProvider } from "styled-components";

import App from "./App";

const rootElement = document.getElementById("root");

const theme = {
  main: "red",
};

render(
  <ThemeProvider theme={theme}>
    <App />
  </ThemeProvider>,
  rootElement
);

When adapting styles based on props, TypeScript automatically recognizes the 

Below is a screenshot of passing a function to a styled component's template literal to adapt its styles based on its props. Notice that TypeScript raises no warnings or errors when you reference the 

 property. In fact, if you happen to use VSCode and hover over 

, then a tooltip with its type definition appears.

 indicates that TypeScript will not raise any warnings no matter what property you try to access from 

 object that might reasonably be available on it like 

, then TypeScript will not raise any warnings for either. Hover over any one of these properties, and a tooltip with the type 

 interface, which is used as the interface of 

 (i.e., we might set the primary color of the default theme to 

import "styled-components";

declare module "styled-components" {
  export interface DefaultTheme {
    primary: string;
  }
}

 declaration file to the list of included files/directories required by TypeScript to compile the project:

{
  "include": ["./src/**/*", "styled.d.ts"]
  // ...
}

 styled component, then you will see TypeScript raising a warning about 

 since we did not define its type within the 

, then a tooltip with its type definition, 

 file, then you will also find TypeScript warning about the 

This issue can be resolved by replacing the 

 and annotate the object with this interface.

const theme: DefaultTheme = {
  primary: "red",
};

 directly to the current theme's primary color.

const S = {
  Card: styled.div`
    width: 18rem;
    border: 1px solid #cbcdcf;
    border-radius: 0.25rem;
    display: flex;
    flex-direction: column;
    position: relative;
    background-color: ${(props) => props.theme.primary};
  `,
  // ...
};

To see the final result, visit this CodeSandbox demo:

https://codesandbox.io/embed/keen-satoshi-fxcir?fontsize=14&hidenavigation=1&theme=dark

Try annotating styled components in your own React applications with TypeScript.

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Tutorials on Styled Components

Annotating React Styled Components with TypeScript

Email Newsletter

Popular Topics

Masterclasses

Tutorials

Fullstack React with TypeScript