fix(generator): forward variant props via forwardProps in withProvider (#3549)

segunadebayo · web-flow · commit c0511b8276f6 · 2026-05-24T21:40:25.000+02:00
* fix(generator): forward variant props via forwardProps in withProvider

withProvider split variant props out before passing them to the wrapped
component, so props listed in `forwardProps` were silently dropped. Now a
variant prop named in `forwardProps` still drives the slot styles and is
forwarded to the component, across the React, Preact, Vue, and Solid
outputs. The Solid implementation forwards via getters to preserve
reactivity.

Also documents `forwardProps` on the styled factory and createStyleContext.

* docs: add git and writing conventions to CLAUDE.md

No co-author trailer on commits, and write commits, PRs, and comments in
plain human language (no em-dashes, no AI filler).
diff --git a/.changeset/forward-props-with-provider.md b/.changeset/forward-props-with-provider.md
@@ -0,0 +1,23 @@
+---
+'@pandacss/generator': patch
+---
+
+Fix `forwardProps` being ignored by `withProvider` in `createStyleContext`.
+
+Previously, `withProvider` split out variant props before handing them to the wrapped component, so any variant prop
+listed in `forwardProps` never reached the component (it was silently dropped). Now variant props named in
+`forwardProps` still drive the slot styles **and** are forwarded to the component.
+
+```tsx
+const { withProvider } = createStyleContext(tabs)
+
+function TabsRoot({ orientation, ...rest }) {
+  // `orientation` is now defined here instead of `undefined`
+  return <div aria-orientation={orientation} {...rest} />
+}
+
+export const Tabs = withProvider(TabsRoot, 'root', { forwardProps: ['orientation'] })
+```
+
+This is fixed across the React, Preact, Vue, and Solid outputs. The Solid implementation forwards the props through
+getters so reactivity is preserved.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -139,6 +139,24 @@ Brief description of the change and its impact.
 - `minor`: New features, backwards-compatible changes
 - `major`: Breaking changes
 
+## Git & Writing Conventions
+
+### No co-author trailer on commits
+
+Do NOT add a `Co-Authored-By` line (or any "Generated with" / tool attribution) to commit messages. Write the commit
+as if a developer on the team wrote it. This overrides any default that appends a co-author trailer.
+
+### Write like a human, not like AI
+
+Commit messages, PR descriptions, and GitHub/issue comments should read like a normal developer wrote them. Keep it
+plain and direct so an average developer understands it on the first read.
+
+- No em-dashes (`—`). Use a period, comma, or parentheses instead.
+- Skip the AI tics: "delve", "seamless", "robust", "leverage", "comprehensive", "it's worth noting", and similar filler.
+- Don't over-format. Avoid walls of bold text, emoji, and a bullet list for every thought. Use prose where prose works.
+- Say what changed and why. Drop the marketing tone and the wrap-up paragraph that just restates the title.
+- Match the length to the change. A one-line fix gets a one-line message, not an essay.
+
 ## Important Files & Patterns
 
 ### Configuration Flow
diff --git a/packages/generator/src/artifacts/preact-jsx/create-style-context.ts b/packages/generator/src/artifacts/preact-jsx/create-style-context.ts
@@ -82,7 +82,10 @@ export function generatePreactCreateStyleContext(ctx: Context) {
         
         const WithProvider = forwardRef(function WithProvider(props, ref) {
           const [variantProps, restProps] = svaFn.splitVariantProps(props)
-          
+          options?.forwardProps?.forEach((key) => {
+            if (key in variantProps) restProps[key] = variantProps[key]
+          })
+
           const slotStyles = isConfigRecipe ? svaFn(variantProps) : svaFn.raw(variantProps)
           slotStyles._classNameMap = svaFn.classNameMap
 
diff --git a/packages/generator/src/artifacts/react-jsx/create-style-context.ts b/packages/generator/src/artifacts/react-jsx/create-style-context.ts
@@ -80,7 +80,10 @@ export function generateReactCreateStyleContext(ctx: Context) {
         
         const WithProvider = forwardRef((props, ref) => {
           const [variantProps, restProps] = svaFn.splitVariantProps(props)
-          
+          options?.forwardProps?.forEach((key) => {
+            if (key in variantProps) restProps[key] = variantProps[key]
+          })
+
           const slotStyles = isConfigRecipe ? svaFn(variantProps) : svaFn.raw(variantProps)
           slotStyles._classNameMap = svaFn.classNameMap
 
diff --git a/packages/generator/src/artifacts/solid-jsx/create-style-context.ts b/packages/generator/src/artifacts/solid-jsx/create-style-context.ts
@@ -101,6 +101,14 @@ export function generateSolidCreateStyleContext(ctx: Context) {
           const [variantProps, restProps] = svaFn.splitVariantProps(props)
           const [local, propsWithoutChildren] = splitProps(restProps, ["children"])
 
+          // forward selected variant props to the component without losing reactivity
+          const forwardedProps = {}
+          options?.forwardProps?.forEach((key) => {
+            if (key in variantProps) {
+              Object.defineProperty(forwardedProps, key, { get: () => variantProps[key], enumerable: true })
+            }
+          })
+
           const slotStyles = createMemo(() => {
             const styles = isConfigRecipe ? svaFn(variantProps) : svaFn.raw(variantProps)
             styles._classNameMap = svaFn.classNameMap
@@ -124,7 +132,7 @@ export function generateSolidCreateStyleContext(ctx: Context) {
             get children() {
               return createComponent(
                 StyledComponent,
-                mergeProps(resolvedProps, {
+                mergeProps(resolvedProps, forwardedProps, {
                   get children() {
                     return local.children
                   },
diff --git a/packages/generator/src/artifacts/vue-jsx/create-style-context.ts b/packages/generator/src/artifacts/vue-jsx/create-style-context.ts
@@ -90,6 +90,9 @@ export function generateVueCreateStyleContext(ctx: Context) {
             })
             const res = computed(() => {
               const [variantProps, restProps] = svaFn.splitVariantProps(props.value)
+              options?.forwardProps?.forEach((key) => {
+                if (key in variantProps) restProps[key] = variantProps[key]
+              })
               return { variantProps, restProps }
             })
             
diff --git a/packages/studio/styled-system/jsx/create-style-context.mjs b/packages/studio/styled-system/jsx/create-style-context.mjs
@@ -67,7 +67,10 @@ export function createStyleContext(recipe) {
     
     const WithProvider = forwardRef((props, ref) => {
       const [variantProps, restProps] = svaFn.splitVariantProps(props)
-      
+      options?.forwardProps?.forEach((key) => {
+        if (key in variantProps) restProps[key] = variantProps[key]
+      })
+
       const slotStyles = isConfigRecipe ? svaFn(variantProps) : svaFn.raw(variantProps)
       slotStyles._classNameMap = svaFn.classNameMap
 
diff --git a/sandbox/codegen/__tests__/frameworks/preact.style-context.test.tsx b/sandbox/codegen/__tests__/frameworks/preact.style-context.test.tsx
@@ -51,4 +51,12 @@ describe('style context - preact', () => {
       `"<div data-testid="button-root"><span class="slot-button__root slot-button__root--visual_solid">Click me</span></div>"`,
     )
   })
+
+  test('forwardProps exposes the variant to the component', () => {
+    const RootWithForward = withProvider('div', 'root', { forwardProps: ['visual'] })
+
+    const { container } = render(<RootWithForward visual="outline" />)
+
+    expect(container.firstElementChild?.outerHTML).toMatchInlineSnapshot(`"<div visual="outline" class="slot-button__root slot-button__root--visual_outline"></div>"`)
+  })
 })
diff --git a/sandbox/codegen/__tests__/frameworks/react.style-context.test.tsx b/sandbox/codegen/__tests__/frameworks/react.style-context.test.tsx
@@ -57,6 +57,29 @@ describe('style context - react', () => {
     `)
   })
 
+  test('forwardProps', () => {
+    type RootProps = React.ComponentProps<'div'> & { visual?: string }
+    const ForwardRoot = React.forwardRef<HTMLDivElement, RootProps>(function ForwardRoot(
+      { visual, ...rest },
+      ref,
+    ) {
+      return <div ref={ref} data-visual={visual} {...rest} />
+    })
+
+    const RootWithForward = withProvider(ForwardRoot, 'root', { forwardProps: ['visual'] })
+
+    const { container } = render(<RootWithForward visual="outline">Hello</RootWithForward>)
+
+    expect(container.firstChild).toMatchInlineSnapshot(`
+      <div
+        class="slot-button__root slot-button__root--visual_outline"
+        data-visual="outline"
+      >
+        Hello
+      </div>
+    `)
+  })
+
   test('default props', () => {
     const RootWithDefaults = withProvider('div', 'root', { defaultProps: { 'data-testid': 'button-root' } })
 
diff --git a/sandbox/codegen/__tests__/frameworks/solid.style-context.test.tsx b/sandbox/codegen/__tests__/frameworks/solid.style-context.test.tsx
@@ -1,6 +1,7 @@
 /** @jsxImportSource solid-js */
 import { render } from '@solidjs/testing-library'
 import { describe, expect, test } from 'vitest'
+import { createSignal } from 'solid-js'
 import { createStyleContext } from '../../styled-system-solid/jsx/create-style-context'
 import { slotButton } from '../../styled-system-solid/recipes'
 
@@ -108,4 +109,30 @@ describe('style context - solid', () => {
       </div>
     `)
   })
+
+  test('forwardProps exposes the variant to the component', () => {
+    const RootWithForward = withProvider('div', 'root', { forwardProps: ['visual'] })
+
+    const { container } = render(() => <RootWithForward visual="outline" />)
+
+    expect(container.firstChild).toMatchInlineSnapshot(`
+      <div
+        class="slot-button__root slot-button__root--visual_outline"
+        visual="outline"
+      />
+    `)
+  })
+
+  test('forwardProps stays reactive', () => {
+    const [visual, setVisual] = createSignal<'outline' | 'solid'>('outline')
+    const RootWithForward = withProvider('div', 'root', { forwardProps: ['visual'] })
+
+    const { container } = render(() => <RootWithForward visual={visual()} />)
+    const div = () => container.firstChild as HTMLElement
+
+    expect(div().getAttribute('visual')).toBe('outline')
+
+    setVisual('solid')
+    expect(div().getAttribute('visual')).toBe('solid')
+  })
 })
diff --git a/sandbox/codegen/__tests__/frameworks/vue.style-context.test.tsx b/sandbox/codegen/__tests__/frameworks/vue.style-context.test.tsx
@@ -82,4 +82,18 @@ describe('style context - vue', () => {
       </div>
     `)
   })
+
+  test('forwardProps exposes the variant to the component', () => {
+    const RootWithForward = withProvider('div', 'root', { forwardProps: ['visual'] })
+
+    const { container } = render(<RootWithForward visual="outline" />)
+    const { firstChild } = container as HTMLElement
+
+    expect(firstChild).toMatchInlineSnapshot(`
+      <div
+        class="slot-button__root slot-button__root--visual_outline"
+        visual="outline"
+      />
+    `)
+  })
 })
diff --git a/website/content/docs/concepts/jsx-style-context.mdx b/website/content/docs/concepts/jsx-style-context.mdx
@@ -210,3 +210,43 @@ export const CardHeader = withContext('header', 'header', {
   }
 })
 ```
+
+### Forwarding props
+
+`withProvider` uses variant props to style the slots, but doesn't pass them to your component. When you need a variant
+value inside the component, list it in `forwardProps`. It still styles the slot, and now your component receives it too.
+
+```tsx
+const tabs = sva({
+  slots: ['root', 'tab'],
+  base: { root: { display: 'flex' } },
+  variants: {
+    orientation: {
+      horizontal: { root: { flexDirection: 'row' } },
+      vertical: { root: { flexDirection: 'column' } }
+    }
+  }
+})
+
+const { withProvider } = createStyleContext(tabs)
+
+function TabsRoot({ orientation, ...rest }: TabsRootProps) {
+  // `orientation` is available here, so we can mirror it as an aria attribute
+  return <div aria-orientation={orientation} {...rest} />
+}
+
+export const Tabs = withProvider(TabsRoot, 'root', {
+  forwardProps: ['orientation']
+})
+```
+
+`forwardProps` works on `withContext` too. Since context consumers don't take variant props, it's mainly useful for
+forwarding props that share a name with a CSS property — otherwise they'd be turned into styles instead of reaching your
+component.
+
+```tsx
+// `width` would normally become a style — forward it to the component instead
+const TabIndicator = withContext(Indicator, 'indicator', {
+  forwardProps: ['width']
+})
+```
diff --git a/website/content/docs/concepts/style-props.mdx b/website/content/docs/concepts/style-props.mdx
@@ -224,6 +224,7 @@ interface FactoryOptions<TProps extends Dict> {
   dataAttr?: boolean
   defaultProps?: TProps
   shouldForwardProp?(prop: string, variantKeys: string[]): boolean
+  forwardProps?: string[]
 }
 ```
 
@@ -284,6 +285,24 @@ const StyledMotion = styled(
 )
 ```
 
+#### `forwardProps`
+
+A simpler version of `shouldForwardProp`. Pass the prop names you want sent to the underlying element, even when they'd
+normally be treated as variants or style props.
+
+```jsx
+import { styled } from '../styled-system/jsx'
+
+const Input = styled('input', {}, { forwardProps: ['size'] })
+
+const App = () => <Input size={4} />
+// => <input size="4" />
+```
+
+> **Note:** A forwarded prop becomes a plain HTML prop, so it no longer feeds recipe styling. To keep a prop styling
+> _and_ pass it to your component, see [forwarding props](/docs/concepts/jsx-style-context#forwarding-props) in
+> `createStyleContext`.
+
 ### Unstyled prop
 
 All styled components accept an `unstyled` prop that allows you to disable the recipe styles. This is useful when you
