If you're using a built-in components like div or span and you want to allow the user to customize the styles via some props.

const MyComponent = styled('div')(({ bgColor }) => ({
  backgroundColor: bgColor,
}));

When you're using it like this:

<MyComponent bgColor='red'>

The prop is passed to the real element in the DOM tree as attribute:

And react will complain, something like:

Warning: React does not recognize the `bgColor` prop on a DOM element. If you intentionally want it to appear in the DOM as a custom attribute, spell it as lowercase `bgcolor` instead. If you accidentally passed it from a parent component, remove it from the DOM element.

This is why shouldForwardProp exists, to prevent styling props from being passed down and create invalid attribute:

const MyComponent = styled('div', {
  shouldForwardProp: (props) => props !== 'bgColor',
})(({ bgColor }) => ({
  backgroundColor: bgColor,
}));
Answer from NearHuscarl on Stack Overflow
🌐
styled-components
styled-components.com › docs › api
styled-components
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}; `;
🌐
Medium
medium.com › @darwish.saja › fixing-shouldforwardprop-warnings-in-styled-components-v6-2b288eaa9fcc
Fixing shouldForwardProp Warnings in Styled Components v6 🛠 | by Saja Darwish | Medium
April 14, 2025 - To bring back the default prop-filtering behavior from Styled Components v5, you can wrap your app in a StyleSheetManager and supply your own shouldForwardProp function.
🌐
Emotion
emotion.sh › docs › styled
Emotion – Styled Components
The as prop is only used by styled ... and forwarded for components. To change this, you can pass a custom shouldForwardProp which returns true for 'as' to forward it or returns false for 'as' to use it and not forward it....
🌐
DEV Community
dev.to › sarahscode › props-are-not-forever-preventing-props-from-being-passed-to-the-dom-with-styled-components-v5-1-l47
Props Are Not Forever: Preventing Props From Being Passed to the DOM with styled-components v5.1 - DEV Community
November 23, 2020 - I recently discovered (thanks to ... and how I plan to use it. shouldForwardProp is a config option that determines if a given prop should be forwarded to the DOM....
🌐
GitHub
github.com › styled-components › styled-components › issues › 4251
StyleSheetManager `shouldForwardProp` does not prevent prop forwarding · Issue #4251 · styled-components/styled-components
January 15, 2024 - styled-components: it looks like an unknown prop "someProp" is being sent through to the DOM, which will likely trigger a React console error. If you would like automatic filtering of unknown props, you can opt-into that behavior via `<StyleSheetManager shouldForwardProp={...}>` (connect an API like `@emotion/is-prop-valid`) or consider using transient props (`$` prefix for automatic filtering.)
Author   charlie-zv
🌐
MUI
mui.com › system › styled
styled() - MUI System
The utility can be used as a replacement for emotion's or styled-components' styled() utility. It aims to solve the same problem, but also provides the following benefits: It uses a default theme if no theme is available in React context.
🌐
GitHub
github.com › styled-components › styled-components › issues › 3541
shouldForwardProp for Transient Props · Issue #3541 · styled-components/styled-components
August 1, 2021 - interface ButtonAttrs { $isCompact?: boolean; } const Button = styled.button<ButtonAttrs>` padding: ${p => p.$isCompact ? '0.5em' : '1em'}; `; const ScaledDownButton = styled(Button).withConfig({ shouldForwardProp: (prop, defaultValidatorFn) => prop !== '$isCompact' && defaultValidatorFn(prop), })<ButtonAttrs>` font-size: ${p => p.$isCompact ?
Author   itayganor
🌐
GitHub
github.com › emotion-js › emotion › issues › 900
shouldForwardProp in styled component · Issue #900 · emotion-js/emotion
October 8, 2018 - I added { shouldForwardProp: isPropValid } to my styled components in react native to prevent the prop isColored from being forwarded. What happened: Using the setup described above, I noticed that the prop isColored is being forwarded. The following error message will be displayed: Warning: React does not recognize the isColored prop on a DOM element.
Author   timomeh
Find elsewhere
🌐
Styled-system
styled-system.com › guides › removing-props-from-html
Styled System
In your styled component definition, pass this utility function as an option to the styled HOC. import styled from '@emotion/styled' import shouldForwardProp from '@styled-system/should-forward-prop' import { space, color } from 'styled-system' const Box = styled('div', { shouldForwardProp, })(space, color)
🌐
Fabrizio Duroni
fabrizioduroni.it › blog › post › 2025 › 01 › 03 › styled-component-transient-props-type-mapped-type-typescript
Styled Components: create a type to define transient props based on the props interface of another component
January 3, 2025 - interface BigCardProps { big: boolean; } const PostCardContainer = styled.div<BigCardProps>` /// ...other css rules... /// usage of the "big" prop ${(props) => !props.$big && css` width: 48%; `}} /// ...other csss rules... `; PostCardContainer.shouldForwardProp = (prop: string) => prop !== "big"; Anyway, both these methods require a manual development specific on the prop names. In particular, it is very tedious when you have a parent component and its children are styled components that should receive the same props.
🌐
CodeSandbox
codesandbox.io › s › styled-components-transient-props-and-shouldforwardprops-bcb46
styled-components transient props and shouldForwardProps - CodeSandbox
April 22, 2021 - styled-components transient props and shouldForwardProps by Jovan27 using @material-ui/core, @types/styled-components, react, react-dom, react-scripts, styled-components
Published   Apr 22, 2021
Author   Jovan27
Top answer
1 of 2
1

In all the APIs that you've used here, you've used them incorrectly. I've annotated the mistakes you've made in this TS Playground link. But I'll add it here as well -

// original
const Thing = styled.div<{
  isSmallContainer: boolean;
}>(({ isSmallContainer }) => ({
  // padding: isSmallContainer ? 12 : '16px 32px',
  // The type of padding in the library is `string & {} | 0` so you can either set it to zero or a string
  padding: isSmallContainer ? "12px" : '16px 32px',
  display: 'flex',
  alignItems: 'center',
}));

const Thing2 = styled(
  'div',
  // The function takes only one argument so can't take BASE_CONFIG
  // BASE_CONFIG 
)<{
  isSmallContainer: boolean;
}>(({ isSmallContainer }) => ({
  // padding: isSmallContainer ? 12 : '16px 32px',
  // The type of padding in the library is `string & {} | 0` so you can either set it to zero or a string
  padding: isSmallContainer ? "12px" : '16px 32px',
  display: 'flex',
  alignItems: 'center',
}));

const Thing3 = styled
  .div<{
    isSmallContainer: boolean;
  }>(({ isSmallContainer }) => ({
    // padding: isSmallContainer ? 12 : '16px 32px',
    // The type of padding in the library is `string & {} | 0` so you can either set it to zero or a string
    padding: isSmallContainer ? "12px" : '16px 32px',
    display: 'flex',
    alignItems: 'center',
  }))
  // Not Supported by API
  // .withConfig(BASE_CONFIG);

const Thing4 = styled
  .div<{
    isSmallContainer: boolean;
  }>
  // .withConfig(BASE_CONFIG) Cannot call a generic
  (({ isSmallContainer }) => ({
    // padding: isSmallContainer ? 12 : '16px 32px',
    // The type of padding in the library is `string & {} | 0` so you can either set it to zero or a string
    padding: isSmallContainer ? "12px" : '16px 32px',
    display: 'flex',
    alignItems: 'center',
  }));

const Thing5 = styled("div")
// .withConfig(BASE_CONFIG) // The params are incorrect
.withConfig({ shouldForwardProp: (prop) => prop === "isSmallContainer" ? false : true })
// Already called styled with `div` argument, no need to call again
// .div<{
//   isSmallContainer: boolean;
// }>
<{isSmallContainer: boolean}>(({ isSmallContainer }) => ({
  // padding: isSmallContainer ? 12 : '16px 32px',
  // The type of padding in the library is `string & {} | 0` so you can either set it to zero or a string
  padding: isSmallContainer ? "12px" : '16px 32px',
  display: 'flex',
  alignItems: 'center',
}));
2 of 2
0
const BASE_IGNORED_PROPS: Array<string | number | symbol> = [
  'isSmallContainer',
];

const BASE_CONFIG: StyledConfig<
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  StyledComponentPropsWithRef<React.ComponentType<any>>
> = {
  shouldForwardProp: (
    prop: string | number | symbol,
    defaultValidatorFn: (prop: string | number | symbol) => boolean
  ) => !BASE_IGNORED_PROPS.includes(prop) && defaultValidatorFn(prop),
};

const Thing = styled.div(({ theme }) => ({
  flex: '0 1 100%',
}));

const ThingInner = styled(Flex).withConfig(BASE_CONFIG)<{
  isSmallContainer: boolean;
}>(({ isSmallContainer }) => ({
  width: '100%',
  padding: isSmallContainer ? 12 : 32,
  paddingBottom: 0,
}));
🌐
GitHub
github.com › styled-components › styled-components › issues › 3427
shouldForwardProp before each styled component? · Issue #3427 · styled-components/styled-components
March 10, 2021 - I need to pass additional settings to the styled components by withConfig method: const Comp = styled('div').withConfig({ shouldForwardProp: (prop, defaultValidatorFn) => !['hidden'].includes(prop) && defaultValidatorFn(prop), }).attrs({ className: 'foo' })` color: red; &.foo { text-decoration: underline; } `; Should I pass this "withConfig" on each component separately?
Author   marcin-piechaczek
🌐
Jynx
jynx.vercel.app › utilities › should-forward-prop
shouldForwardProp | Jynx
/* Import the `shouldForwardProp` utility along with any required functions */ /* and their corresponding props types */ import { color, ColorProps, shouldForwardProp } from 'jynx' /* Then create a component, chaining to it the `withConfig` method, */ /* and including `shouldForwardProp` in your argument object */ export const Component = styled('div').withConfig<ColorProps>({ shouldForwardProp })` ${color} ` /* Or using the legacy functional syntax */ export const Component = styled('div').withConfig<ColorProps>({ shouldForwardProp })(props => ` ${color} `)
🌐
GitHub
github.com › styled-components › styled-components › issues › 4071
v6: using `styled(Component)` results in `looks like an unknown prop is being sent through to the DOM` · Issue #4071 · styled-components/styled-components
July 2, 2023 - styled-components: it looks like an unknown prop "message" is being sent through to the DOM, which will likely trigger a React console error. If you would like automatic filtering of unknown props, you can opt-into that behavior via `<StyleSheetManager shouldForwardProp={...}>` (connect an API like `@emotion/is-prop-valid`) or consider using transient props (`$` prefix for automatic filtering.)
Author   zackheil
🌐
DEV Community
dev.to › rasaf_ibrahim › styled-components-in-material-ui-mui-with-styled-utility-3l3j
Styled Components in Material UI (MUI) with Styled Utility - DEV Community
October 26, 2023 - shouldForwardProp is a function that can be used with MUI's styled function to control which props should be passed down to the underlying DOM element. By default, all props passed to a styled component will be forwarded to the underlying element.
🌐
CodeSandbox
codesandbox.io › examples › package › @styled-system › should-forward-prop
styled-system/should-forward-prop examples
next-ts-starterA Next.JS powered typescript starter with styled components, styled-system, jest, @testing-library and framer-motion ... AboutUtility for filtering Styled System props with Emotion's shouldForwardProp option150,516Weekly Downloads
🌐
GitHub
github.com › styled-components › styled-components › pull › 3436
feat: pass elementToBeCreated to shouldForwardProp by agriffis · Pull Request #3436 · styled-components/styled-components
The internal decision whether to forward a prop is based on the combination of the key and elementToBeCreated, but only the former was passed to shouldForwardProp. This is a port of styled-components#3436 to legacy-v5
Author   styled-components