styled-components Best Practices You are an expert in styled-components, CSS-in-JS patterns, and React component styling. Key Principles Write component-scoped styles that avoid global CSS conflicts Leverage the full power of JavaScript for dynamic styling Keep styled components small, focused, and reusable Prioritize performance with proper memoization and SSR support Basic Setup Installation npm install styled-components npm install -D @types/styled-components
For TypeScript
Basic Usage
import
styled
from
'styled-components'
;
const
Button
=
styled
.
button
display: inline-flex;
align-items: center;
justify-content: center;
padding: 8px 16px;
background-color: #3498db;
color: white;
border: none;
border-radius: 4px;
font-size: 1rem;
cursor: pointer;
transition: background-color 0.3s ease;
&:hover {
background-color: #2980b9;
}
&:disabled {
opacity: 0.5;
cursor: not-allowed;
}
;
// Usage
function
App
(
)
{
return
<
Button
Click me </ Button
; } Project Structure File Organization src/ ├── components/ │ ├── Button/ │ │ ├── Button.tsx │ │ ├── Button.styles.ts # Styled components │ │ ├── Button.types.ts # TypeScript types │ │ └── index.ts # Re-exports │ ├── Card/ │ │ ├── Card.tsx │ │ ├── Card.styles.ts │ │ └── index.ts │ └── index.ts ├── styles/ │ ├── theme.ts # Theme definition │ ├── GlobalStyles.ts # Global styles │ ├── mixins.ts # Reusable style mixins │ └── index.ts └── App.tsx Component Style File // Button.styles.ts import styled , { css } from 'styled-components' ; import type { ButtonProps } from './Button.types' ; export const StyledButton = styled . button < Pick < ButtonProps , 'variant' | 'size'
display: inline-flex; align-items: center; justify-content: center; border: none; border-radius: ${ ( { theme } ) => theme . borderRadius . md } ; font-family: inherit; font-weight: ${ ( { theme } ) => theme . fontWeight . medium } ; cursor: pointer; transition: all ${ ( { theme } ) => theme . transition . base } ; ${ ( { size , theme } ) => { switch ( size ) { case 'small' : return csspadding: ${ theme . spacing . xs } ${ theme . spacing . sm } ; font-size: ${ theme . fontSize . small } ;; case 'large' : return csspadding: ${ theme . spacing . md } ${ theme . spacing . lg } ; font-size: ${ theme . fontSize . large } ;; default : return csspadding: ${ theme . spacing . sm } ${ theme . spacing . md } ; font-size: ${ theme . fontSize . base } ;; } } } ${ ( { variant , theme } ) => { switch ( variant ) { case 'secondary' : return cssbackground-color: transparent; color: ${ theme . colors . primary } ; border: 2px solid ${ theme . colors . primary } ; &:hover:not(:disabled) { background-color: ${ theme . colors . primary } ; color: white; }; case 'danger' : return cssbackground-color: ${ theme . colors . error } ; color: white; &:hover:not(:disabled) { background-color: ${ theme . colors . errorDark } ; }; default : return cssbackground-color: ${ theme . colors . primary } ; color: white; &:hover:not(:disabled) { background-color: ${ theme . colors . primaryDark } ; }; } }} &:disabled { opacity: 0.5; cursor: not-allowed; }; export const ButtonIcon = styled . spandisplay: inline-flex; margin-right: ${ ( { theme } ) => theme . spacing . xs } ;; Theming Theme Definition // styles/theme.ts export const theme = { colors : { primary : '#3498db' , primaryLight : '#5dade2' , primaryDark : '#2980b9' , secondary : '#2ecc71' , secondaryLight : '#58d68d' , secondaryDark : '#27ae60' , error : '#e74c3c' , errorLight : '#ec7063' , errorDark : '#c0392b' , warning : '#f39c12' , success : '#27ae60' , info : '#17a2b8' , text : '#333333' , textMuted : '#666666' , textLight : '#999999' , background : '#ffffff' , backgroundAlt : '#f8f9fa' , border : '#e0e0e0' , borderDark : '#cccccc' , } , spacing : { xs : '4px' , sm : '8px' , md : '16px' , lg : '24px' , xl : '32px' , xxl : '48px' , } , fontSize : { xs : '0.75rem' , small : '0.875rem' , base : '1rem' , large : '1.25rem' , xl : '1.5rem' , xxl : '2rem' , xxxl : '2.5rem' , } , fontWeight : { normal : 400 , medium : 500 , semibold : 600 , bold : 700 , } , fontFamily : { base : "'Helvetica Neue', Arial, sans-serif" , heading : "'Georgia', serif" , mono : "'Consolas', monospace" , } , lineHeight : { tight : 1.2 , base : 1.5 , relaxed : 1.75 , } , borderRadius : { sm : '2px' , md : '4px' , lg : '8px' , xl : '16px' , pill : '50px' , circle : '50%' , } , shadow : { sm : '0 1px 2px rgba(0, 0, 0, 0.05)' , md : '0 4px 6px rgba(0, 0, 0, 0.1)' , lg : '0 10px 15px rgba(0, 0, 0, 0.1)' , xl : '0 20px 25px rgba(0, 0, 0, 0.15)' , } , transition : { fast : '0.15s ease' , base : '0.3s ease' , slow : '0.5s ease' , } , breakpoints : { sm : '576px' , md : '768px' , lg : '992px' , xl : '1200px' , xxl : '1400px' , } , zIndex : { dropdown : 1000 , sticky : 1020 , fixed : 1030 , modalBackdrop : 1040 , modal : 1050 , popover : 1060 , tooltip : 1070 , } , } as const ; export type Theme = typeof theme ; TypeScript Theme Typing // styles/styled.d.ts import 'styled-components' ; import type { Theme } from './theme' ; declare module 'styled-components' { export interface DefaultTheme extends Theme { } } Theme Provider Setup // App.tsx import { ThemeProvider } from 'styled-components' ; import { theme } from './styles/theme' ; import { GlobalStyles } from './styles/GlobalStyles' ; function App ( ) { return ( < ThemeProvider theme = { theme }< GlobalStyles /> { / App content / } </ ThemeProvider
) ; } Global Styles // styles/GlobalStyles.ts import { createGlobalStyle } from 'styled-components' ; export const GlobalStyles = createGlobalStyle
*, *::before, *::after { box-sizing: border-box; } html { font-size: 16px; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; } body { margin: 0; padding: 0; font-family: ${ ( { theme } ) => theme . fontFamily . base } ; font-size: ${ ( { theme } ) => theme . fontSize . base } ; line-height: ${ ( { theme } ) => theme . lineHeight . base } ; color: ${ ( { theme } ) => theme . colors . text } ; background-color: ${ ( { theme } ) => theme . colors . background } ; } h1, h2, h3, h4, h5, h6 { font-family: ${ ( { theme } ) => theme . fontFamily . heading } ; font-weight: ${ ( { theme } ) => theme . fontWeight . bold } ; line-height: ${ ( { theme } ) => theme . lineHeight . tight } ; margin-top: 0; margin-bottom: ${ ( { theme } ) => theme . spacing . md } ; } p { margin-top: 0; margin-bottom: ${ ( { theme } ) => theme . spacing . md } ; } a { color: ${ ( { theme } ) => theme . colors . primary } ; text-decoration: none; &:hover { text-decoration: underline; } } button { font-family: inherit; } img { max-width: 100%; height: auto; } /* Focus styles for accessibility */ :focus-visible { outline: 2px solid ${ ( { theme } ) => theme . colors . primary } ; outline-offset: 2px; }; Dynamic Styling Props-Based Styling import styled , { css } from 'styled-components' ; interface CardProps { $elevated ? : boolean ; $variant ? : 'default' | 'outlined' | 'filled' ; } const Card = styled . div < CardProps
border-radius: ${ ( { theme } ) => theme . borderRadius . lg } ; padding: ${ ( { theme } ) => theme . spacing . md } ; transition: box-shadow ${ ( { theme } ) => theme . transition . base } ; ${ ( { $variant , theme } ) => { switch ( $variant ) { case 'outlined' : return cssbackground: transparent; border: 1px solid ${ theme . colors . border } ;; case 'filled' : return cssbackground: ${ theme . colors . backgroundAlt } ; border: none;; default : return cssbackground: ${ theme . colors . background } ; border: 1px solid ${ theme . colors . border } ;; } } } ${ ( { $elevated , theme } ) => $elevated && cssbox-shadow: ${ theme . shadow . md } ; &:hover { box-shadow: ${ theme . shadow . lg } ; }}; // Usage with transient props ($prefix) < Card $elevated $variant = " outlined "Content </ Card
Using CSS Helper import styled , { css } from 'styled-components' ; // Reusable style blocks const flexCenter = css
display: flex; align-items: center; justify-content: center;; const truncate = csswhite-space: nowrap; overflow: hidden; text-overflow: ellipsis;; const visuallyHidden = cssposition: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0;; const Container = styled . div${ flexCenter } min-height: 100vh;; const Title = styled . h1${ truncate } max-width: 300px;; const SrOnly = styled . span${ visuallyHidden }; Extending Components Extending Styled Components const Button = styled . buttonpadding: 8px 16px; border: none; border-radius: 4px; cursor: pointer;; const PrimaryButton = styled ( Button )background: #3498db; color: white; &:hover { background: #2980b9; }; const OutlinedButton = styled ( Button )background: transparent; color: #3498db; border: 2px solid #3498db; &:hover { background: #3498db; color: white; }; Extending Third-Party Components import { Link } from 'react-router-dom' ; const StyledLink = styled ( Link )color: ${ ( { theme } ) => theme . colors . primary } ; text-decoration: none; font-weight: ${ ( { theme } ) => theme . fontWeight . medium } ; &:hover { text-decoration: underline; }; Responsive Design Media Query Helpers // styles/mixins.ts import { css } from 'styled-components' ; import type { Theme } from './theme' ; type Breakpoint = keyof Theme [ 'breakpoints' ] ; export const media = { up : ( breakpoint : Breakpoint ) => ( styles : ReturnType < typeof css) => css
@media (min-width: ${ ( { theme } ) => theme . breakpoints [ breakpoint ] } ) { ${ styles } }, down : ( breakpoint : Breakpoint ) => ( styles : ReturnType < typeof css) => css
@media (max-width: calc( ${ ( { theme } ) => theme . breakpoints [ breakpoint ] } - 1px)) { ${ styles } }, } ; // Usage const Container = styled . divpadding: ${ ( { theme } ) => theme . spacing . sm } ; ${ ( { theme } ) => css@media (min-width: ${ theme . breakpoints . md } ) { padding: ${ theme . spacing . md } ; } @media (min-width: ${ theme . breakpoints . lg } ) { padding: ${ theme . spacing . lg } ; }}; Responsive Component const Grid = styled . divdisplay: grid; gap: ${ ( { theme } ) => theme . spacing . md } ; grid-template-columns: 1fr; @media (min-width: ${ ( { theme } ) => theme . breakpoints . sm } ) { grid-template-columns: repeat(2, 1fr); } @media (min-width: ${ ( { theme } ) => theme . breakpoints . md } ) { grid-template-columns: repeat(3, 1fr); } @media (min-width: ${ ( { theme } ) => theme . breakpoints . lg } ) { grid-template-columns: repeat(4, 1fr); }; Animations Keyframes import styled , { keyframes } from 'styled-components' ; const fadeIn = keyframesfrom { opacity: 0; transform: translateY(-10px); } to { opacity: 1; transform: translateY(0); }; const spin = keyframesfrom { transform: rotate(0deg); } to { transform: rotate(360deg); }; const pulse = keyframes0%, 100% { opacity: 1; } 50% { opacity: 0.5; }; const FadeInDiv = styled . divanimation: ${ fadeIn } 0.3s ease-out;; const Spinner = styled . divwidth: 40px; height: 40px; border: 3px solid ${ ( { theme } ) => theme . colors . border } ; border-top-color: ${ ( { theme } ) => theme . colors . primary } ; border-radius: 50%; animation: ${ spin } 1s linear infinite;; const PulsingDot = styled . spananimation: ${ pulse } 2s ease-in-out infinite;; Transition Groups import styled from 'styled-components' ; const Modal = styled . div < { $isOpen : boolean }
position: fixed; inset: 0; display: flex; align-items: center; justify-content: center; background: rgba(0, 0, 0, 0.5); opacity: ${ ( { $isOpen } ) => ( $isOpen ? 1 : 0 ) } ; visibility: ${ ( { $isOpen } ) => ( $isOpen ? 'visible' : 'hidden' ) } ; transition: opacity 0.3s ease, visibility 0.3s ease;; const ModalContent = styled . div < { $isOpen : boolean }
background: white; padding: ${ ( { theme } ) => theme . spacing . lg } ; border-radius: ${ ( { theme } ) => theme . borderRadius . lg } ; transform: ${ ( { $isOpen } ) => ( $isOpen ? 'scale(1)' : 'scale(0.95)' ) } ; transition: transform 0.3s ease;; Performance Optimization Avoid Interpolation in Static Styles // BAD: Creates new class on every render const BadButton = styled . buttonpadding: ${ 8 } px ${ 16 } px; background: ${ '#3498db' } ;; // GOOD: Static values don't need interpolation const GoodButton = styled . buttonpadding: 8px 16px; background: #3498db;; // GOOD: Theme values are cached const ThemedButton = styled . buttonpadding: ${ ( { theme } ) => theme . spacing . sm } ${ ( { theme } ) => theme . spacing . md } ; background: ${ ( { theme } ) => theme . colors . primary } ;; Use Transient Props // Use $ prefix for props that shouldn't be passed to DOM interface StyledProps { $isActive : boolean ; $size : 'small' | 'medium' | 'large' ; } const StyledDiv = styled . div < StyledProps
opacity: ${ ( { $isActive } ) => ( $isActive ? 1 : 0.5 ) } ; padding: ${ ( { $size , theme } ) => $size === 'small' ? theme . spacing . sm : theme . spacing . md } ;; // Props with $ prefix won't appear in DOM < StyledDiv $isActive = { true } $size = " medium " /> Memoize Complex Components import { memo } from 'react' ; import styled from 'styled-components' ; const StyledCard = styled . div/* styles */; interface CardProps { title : string ; description : string ; } const Card = memo ( ( { title , description } : CardProps ) => ( < StyledCard< h2
{ title } </ h2
< p
{ description } </ p
</ StyledCard
) ) ; SSR Configuration // For Next.js - next.config.js module . exports = { compiler : { styledComponents : true , } , } ; // For other frameworks - use ServerStyleSheet import { ServerStyleSheet , StyleSheetManager } from 'styled-components' ; const sheet = new ServerStyleSheet ( ) ; try { const html = renderToString ( < StyleSheetManager sheet = { sheet . instance }
< App /> </ StyleSheetManager
) ; const styleTags = sheet . getStyleTags ( ) ; } finally { sheet . seal ( ) ; } Best Practices Naming Conventions // Prefix styled components for clarity export const StyledButton = styled . button
; export const StyledCard = styled . div; // Or use descriptive names export const ButtonWrapper = styled . div; export const CardContainer = styled . article; export const NavigationList = styled . ul; Composition Over Inheritance // Prefer composition const BaseText = styled . pfont-family: ${ ( { theme } ) => theme . fontFamily . base } ; line-height: ${ ( { theme } ) => theme . lineHeight . base } ;; const Heading = styled ( BaseText ) . attrs ( { as : 'h1' } )font-size: ${ ( { theme } ) => theme . fontSize . xxl } ; font-weight: ${ ( { theme } ) => theme . fontWeight . bold } ;; const Caption = styled ( BaseText )font-size: ${ ( { theme } ) => theme . fontSize . small } ; color: ${ ( { theme } ) => theme . colors . textMuted } ;; Use attrs for Static Props const Input = styled . input . attrs ( props => ( { type : props . type || 'text' , placeholder : props . placeholder || 'Enter text...' , } ) )padding: ${ ( { theme } ) => theme . spacing . sm } ; border: 1px solid ${ ( { theme } ) => theme . colors . border } ; border-radius: ${ ( { theme } ) => theme . borderRadius . md } ; &:focus { border-color: ${ ( { theme } ) => theme . colors . primary } ; outline: none; }; Accessibility const IconButton = styled . buttondisplay: inline-flex; align-items: center; justify-content: center; width: 44px; /* Minimum touch target */ height: 44px; padding: 0; background: transparent; border: none; cursor: pointer; &:focus-visible { outline: 2px solid ${ ( { theme } ) => theme . colors . primary } ; outline-offset: 2px; }; const VisuallyHidden = styled . spanposition: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0;; // Usage < IconButton aria-label = " Close menu "< CloseIcon /> < VisuallyHidden
Close menu </ VisuallyHidden
</ IconButton
Testing Testing Styled Components import { render , screen } from '@testing-library/react' ; import { ThemeProvider } from 'styled-components' ; import { theme } from './styles/theme' ; import { Button } from './components/Button' ; const renderWithTheme = ( component : React . ReactElement ) => { return render ( < ThemeProvider theme = { theme }
{ component } </ ThemeProvider
) ; } ; describe ( 'Button' , ( ) => { it ( 'renders with correct styles' , ( ) => { renderWithTheme ( < Button variant = " primary "
Click me </ Button
) ; const button = screen . getByRole ( 'button' ) ; expect ( button ) . toHaveStyle ( { backgroundColor : theme . colors . primary , } ) ; } ) ; } ) ; Code Style One styled component per declaration Order: component declaration, styled components, types Use template literal syntax for multi-line styles Use css helper for reusable style blocks Prefix transient props with $ Keep styled components close to their usage Extract shared styles into mixins or theme