Transient $ props leak through custom shouldForwardProp in styled-components v5+

Answer

In styled‑components v5+ a custom shouldForwardProp replaces the library’s built‑in filter entirely. The default filter removes props that start with a dollar sign ($), but that logic is not composed automatically when you supply your own function. Therefore, to keep transient props from reaching the DOM you must explicitly test for a leading $ inside your custom function and return false for those keys.

Confirmed facts

• A custom shouldForwardProp overrides the default implementation; the library does not export a public defaultShouldForwardProp or a composition helper.
• When you supply a custom function, $-prefixed props will be forwarded to the DOM unless you filter them yourself.
• TypeScript typings for styled() do not automatically strip $ props from the component’s public prop interface; consumers must explicitly apply Omit or a similar helper.
• Community work‑arounds that import internal utilities (e.g. styled-components/dist/utils) are fragile and may break with minor releases.

Likely explanation

The replacement semantics appear intentional, giving developers full control over forwarding logic. The lack of a public composition API and the absence of automatic type stripping suggest a design gap rather than an undocumented feature.

Steps needed for this case

1. Wrap your custom logic with the transient check:

   import styled from 'styled-components';
   
   const shouldForwardProp = (key: string) => {
     if (key.startsWith('$')) return false;
     // your custom rules
     return key !== 'internalProp';
   };
   
   const Box = styled.div.withConfig({ shouldForwardProp })`
     color: ${p => p.$color};
   `;
   

2. Apply the same check consistently for all styled components that use a custom shouldForwardProp.
3. Fix the TypeScript surface separately: define the component’s props and explicitly omit $ keys if you want them hidden from the public API.

Verification

• Render the component with a prop named $test and inspect the output element. If $test appears as an attribute, the filter is missing.
• Render the same component without a custom shouldForwardProp to confirm that the default implementation omits $test.
• Run the TypeScript compiler on a usage site; without an explicit Omit the $test prop will be accepted, illustrating the type‑safety gap.

One missing diagnostic that could change the recommendation: the exact major version of styled‑components in use (v5 vs v6) and whether the target is a DOM element or a custom React component, as forwarding rules differ slightly between these contexts.