feat: add unstyled prop to styled factory

segunadebayo · segunadebayo · commit 50dcd37c271e · 2025-08-27T15:04:56.000+01:00
diff --git a/.changeset/grumpy-cobras-win.md b/.changeset/grumpy-cobras-win.md
@@ -3,3 +3,18 @@
 ---
 
 - Add reset styles for `::selection` pseudo element that maps to `var(--global-color-selection, revert)`.
+- Add support for `unstyled` prop in the `styled` factory. This makes it possible to opt out recipe styles as needed.
+
+```tsx
+const Notice = styled('div', {
+  base: {
+    bg: 'red',
+    color: 'white',
+  },
+})
+
+// This will remove the recipe styles and only apply the inline styles
+<Notice unstyled bg="pink" color="green">
+  Hello
+</Notice>
+```
diff --git a/packages/generator/src/artifacts/preact-jsx/jsx.ts b/packages/generator/src/artifacts/preact-jsx/jsx.ts
@@ -36,7 +36,7 @@ export function generatePreactJsxFactory(ctx: Context) {
       const __base__ = Dynamic.__base__ || Dynamic
 
       const ${componentName} = /* @__PURE__ */ forwardRef(function ${componentName}(props, ref) {
-        const { as: Element = __base__, children, ...restProps } = props
+        const { as: Element = __base__, unstyled, children, ...restProps } = props
 
 
         const combinedProps = useMemo(() => Object.assign({}, defaultProps, restProps), [restProps])
@@ -57,7 +57,13 @@ export function generatePreactJsxFactory(ctx: Context) {
           return cx(css(cvaStyles, propStyles, cssStyles), combinedProps.class, combinedProps.className)
         }
 
-        const classes = configOrCva.__recipe__ ? recipeClass : cvaClass
+        const classes = () => {
+          if (unstyled) {
+            const { css: cssStyles, ...propStyles } = styleProps
+            return cx(css(propStyles, cssStyles), combinedProps.class, combinedProps.className)
+          }
+          return configOrCva.__recipe__ ? recipeClass() : cvaClass()
+        }
 
         return h(Element, {
           ...forwardedProps,
diff --git a/packages/generator/src/artifacts/preact-jsx/types.ts b/packages/generator/src/artifacts/preact-jsx/types.ts
@@ -23,8 +23,15 @@ interface Dict {
   [k: string]: unknown
 }
 
+export interface UnstyledProps {
+  /**
+   * Whether to remove recipe styles
+   */
+  unstyled?: boolean | undefined
+}
+
 export interface ${componentName}<T extends ElementType, P extends Dict = {}> {
-  (props: JsxHTMLProps<ComponentProps<T>, Assign<JsxStyleProps, P>>): JSX.Element
+  (props: JsxHTMLProps<ComponentProps<T> & UnstyledProps, Assign<JsxStyleProps, P>>): JSX.Element
   displayName?: string
 }
 
@@ -39,7 +46,7 @@ export interface JsxFactoryOptions<TProps extends Dict> {
   forwardProps?: string[]
 }
 
-export type JsxRecipeProps<T extends ElementType, P extends Dict> = JsxHTMLProps<ComponentProps<T>, P>
+export type JsxRecipeProps<T extends ElementType, P extends Dict> = JsxHTMLProps<ComponentProps<T> & UnstyledProps, P>
 
 export type JsxElement<T extends ElementType, P extends Dict> = T extends ${componentName}<infer A, infer B>
   ? ${componentName}<A, Pretty<DistributiveUnion<P, B>>>
@@ -60,7 +67,7 @@ export type JsxElements = {
 
 export type ${upperName} = JsxFactory & JsxElements
 
-export type ${typeName}<T extends ElementType> = JsxHTMLProps<ComponentProps<T>, JsxStyleProps>
+export type ${typeName}<T extends ElementType> = JsxHTMLProps<ComponentProps<T> & UnstyledProps, JsxStyleProps>
 
 export type ${variantName}<T extends ${componentName}<any, any>> = T extends ${componentName}<any, infer Props> ? Props : never
   `,
diff --git a/packages/generator/src/artifacts/qwik-jsx/jsx.ts b/packages/generator/src/artifacts/qwik-jsx/jsx.ts
@@ -34,7 +34,7 @@ export function generateQwikJsxFactory(ctx: Context) {
       const __base__ = Dynamic.__base__ || Dynamic
 
       const ${componentName} = function ${componentName}(props) {
-        const { as: Element = __base__, children, className, ...restProps } = props
+        const { as: Element = __base__, unstyled, children, className, ...restProps } = props
 
         const combinedProps = Object.assign({}, defaultProps, restProps)
 
@@ -55,7 +55,13 @@ export function generateQwikJsxFactory(ctx: Context) {
           return cx(css(cvaStyles, propStyles, cssStyles), combinedProps.class, className)
         }
 
-        const classes = configOrCva.__recipe__ ? recipeClass : cvaClass
+        const classes = () => {
+          if (unstyled) {
+            const { css: cssStyles, ...propStyles } = styleProps
+            return cx(css(propStyles, cssStyles), combinedProps.class, className)
+          }
+          return configOrCva.__recipe__ ? recipeClass() : cvaClass()
+        }
 
         return h(Element, {
           ...forwardedProps,
diff --git a/packages/generator/src/artifacts/qwik-jsx/types.ts b/packages/generator/src/artifacts/qwik-jsx/types.ts
@@ -29,7 +29,14 @@ interface Dict {
   [k: string]: unknown
 }
 
-export interface ${componentName}<T extends ElementType, P extends Dict = {}> extends Component<Assign<ComponentProps<T>, Assign<PatchedHTMLProps, Assign<JsxStyleProps, P>>>> {}
+export interface UnstyledProps {
+  /**
+   * Whether to remove recipe styles
+   */
+  unstyled?: boolean | undefined
+}
+
+export interface ${componentName}<T extends ElementType, P extends Dict = {}> extends Component<Assign<ComponentProps<T> & UnstyledProps, Assign<PatchedHTMLProps, Assign<JsxStyleProps, P>>>> {}
 
 interface RecipeFn {
   __type: any
@@ -42,7 +49,7 @@ export interface JsxFactoryOptions<TProps extends Dict> {
   forwardProps?: string[]
 }
 
-export type JsxRecipeProps<T extends ElementType, P extends Dict> = JsxHTMLProps<ComponentProps<T>, P>;
+export type JsxRecipeProps<T extends ElementType, P extends Dict> = JsxHTMLProps<ComponentProps<T> & UnstyledProps, P>;
 
 export type JsxElement<T extends ElementType, P extends Dict> = T extends ${componentName}<infer A, infer B>
   ? ${componentName}<A, Pretty<DistributiveUnion<P, B>>>
@@ -63,7 +70,7 @@ export type JsxElements = {
 
 export type ${upperName} = JsxFactory & JsxElements
 
-export type ${typeName}<T extends ElementType> = Assign<ComponentProps<T>, JsxStyleProps>
+export type ${typeName}<T extends ElementType> = Assign<ComponentProps<T> & UnstyledProps, JsxStyleProps>
 
 export type ${variantName}<T extends ${componentName}<any, any>> = T extends ${componentName}<any, infer Props> ? Props : never
   `,
diff --git a/packages/generator/src/artifacts/react-jsx/jsx.ts b/packages/generator/src/artifacts/react-jsx/jsx.ts
@@ -34,7 +34,7 @@ export function generateReactJsxFactory(ctx: Context) {
       const __base__ = Dynamic.__base__ || Dynamic
 
       const ${componentName} = /* @__PURE__ */ forwardRef(function ${componentName}(props, ref) {
-        const { as: Element = __base__, children, ...restProps } = props
+        const { as: Element = __base__, unstyled, children, ...restProps } = props
 
         const combinedProps = useMemo(() => Object.assign({}, defaultProps, restProps), [restProps])
 
@@ -54,7 +54,13 @@ export function generateReactJsxFactory(ctx: Context) {
           return cx(css(cvaStyles, propStyles, cssStyles), combinedProps.className)
         }
 
-        const classes = configOrCva.__recipe__ ? recipeClass : cvaClass
+        const classes = () => {
+          if (unstyled) {
+            const { css: cssStyles, ...propStyles } = styleProps
+            return cx(css(propStyles, cssStyles), combinedProps.className)
+          }
+          return configOrCva.__recipe__ ? recipeClass() : cvaClass()
+        }
 
         return createElement(Element, {
           ref,
diff --git a/packages/generator/src/artifacts/react-jsx/types.ts b/packages/generator/src/artifacts/react-jsx/types.ts
@@ -21,12 +21,19 @@ interface Dict {
   [k: string]: unknown
 }
 
+export interface UnstyledProps {
+  /**
+   * Whether to remove recipe styles
+   */
+  unstyled?: boolean | undefined
+}
+
 export type ComponentProps<T extends ElementType> = DistributiveOmit<ComponentPropsWithoutRef<T>, 'ref'> & {
   ref?: Ref<ElementRef<T>>
 }
 
 export interface ${componentName}<T extends ElementType, P extends Dict = {}> {
-  (props: JsxHTMLProps<ComponentProps<T>, Assign<JsxStyleProps, P>>): JSX.Element
+  (props: JsxHTMLProps<ComponentProps<T> & UnstyledProps, Assign<JsxStyleProps, P>>): JSX.Element
   displayName?: string
 }
 
@@ -41,7 +48,7 @@ interface JsxFactoryOptions<TProps extends Dict> {
   forwardProps?: string[]
 }
 
-export type JsxRecipeProps<T extends ElementType, P extends Dict> = JsxHTMLProps<ComponentProps<T>, P>;
+export type JsxRecipeProps<T extends ElementType, P extends Dict> = JsxHTMLProps<ComponentProps<T> & UnstyledProps, P>;
 
 export type JsxElement<T extends ElementType, P extends Dict> = T extends ${componentName}<infer A, infer B>
   ? ${componentName}<A, Pretty<DistributiveUnion<P, B>>>
@@ -62,7 +69,7 @@ export type JsxElements = {
 
 export type ${upperName} = JsxFactory & JsxElements
 
-export type ${typeName}<T extends ElementType> = JsxHTMLProps<ComponentProps<T>, JsxStyleProps>
+export type ${typeName}<T extends ElementType> = JsxHTMLProps<ComponentProps<T> & UnstyledProps, JsxStyleProps>
 
 export type ${variantName}<T extends ${componentName}<any, any>> = T extends ${componentName}<any, infer Props> ? Props : never
   `,
diff --git a/packages/generator/src/artifacts/solid-jsx/jsx.ts b/packages/generator/src/artifacts/solid-jsx/jsx.ts
@@ -49,6 +49,7 @@ export function generateSolidJsxFactory(ctx: Context) {
 
         const [localProps, restProps] = splitProps(mergedProps, [
           'as',
+          'unstyled',
           'class',
           'className',
         ])
@@ -91,7 +92,13 @@ export function generateSolidJsxFactory(ctx: Context) {
           )
         }
 
-        const classes = configOrCva.__recipe__ ? recipeClass : cvaClass
+        const classes = () => {
+          if (localProps.unstyled) {
+            const { css: cssStyles, ...propStyles } = styleProps
+            return cx(css(propStyles, cssStyles), localProps.class, localProps.className)
+          }
+          return configOrCva.__recipe__ ? recipeClass() : cvaClass()
+        }
 
         if (forwardedProps.className) {
           delete forwardedProps.className
diff --git a/packages/generator/src/artifacts/solid-jsx/types.ts b/packages/generator/src/artifacts/solid-jsx/types.ts
@@ -21,10 +21,17 @@ interface Dict {
   [k: string]: unknown
 }
 
+export interface UnstyledProps {
+  /**
+   * Whether to remove recipe styles
+   */
+  unstyled?: boolean | undefined
+}
+
 export type ElementType<P = any> = keyof JSX.IntrinsicElements | Component<P>
 
 export interface ${componentName}<T extends ElementType, P extends Dict = {}> {
-  (props: JsxHTMLProps<ComponentProps<T>, Assign<JsxStyleProps, P>>): JSX.Element
+  (props: JsxHTMLProps<ComponentProps<T> & UnstyledProps, Assign<JsxStyleProps, P>>): JSX.Element
   displayName?: string
 }
 
@@ -39,7 +46,7 @@ export interface JsxFactoryOptions<TProps extends Dict> {
   forwardProps?: string[]
 }
 
-export type JsxRecipeProps<T extends ElementType, P extends Dict> = JsxHTMLProps<ComponentProps<T>, P>;
+export type JsxRecipeProps<T extends ElementType, P extends Dict> = JsxHTMLProps<ComponentProps<T> & UnstyledProps, P>;
 
 export type JsxElement<T extends ElementType, P extends Dict> = T extends ${componentName}<infer A, infer B>
   ? ${componentName}<A, Pretty<DistributiveUnion<P, B>>>
@@ -60,7 +67,7 @@ export type JsxElements = {
 
 export type ${upperName} = JsxFactory & JsxElements
 
-export type ${typeName}<T extends ElementType> = JsxHTMLProps<ComponentProps<T>, JsxStyleProps>
+export type ${typeName}<T extends ElementType> = JsxHTMLProps<ComponentProps<T> & UnstyledProps, JsxStyleProps>
 
 export type ${variantName}<T extends ${componentName}<any, any>> = T extends ${componentName}<any, infer Props> ? Props : never
   `,
diff --git a/packages/generator/src/artifacts/vue-jsx/jsx.ts b/packages/generator/src/artifacts/vue-jsx/jsx.ts
@@ -40,6 +40,7 @@ export function generateVueJsxFactory(ctx: Context) {
         inheritAttrs: false,
         props: {
           modelValue: null,
+          unstyled: { type: Boolean, default: false },
           as: { type: [String, Object], default: __base__ }
         },
         setup(props, { slots, attrs, emit }) {
@@ -63,7 +64,14 @@ export function generateVueJsxFactory(ctx: Context) {
             return cx(css(cvaStyles, propStyles, cssStyles), combinedProps.value.className, combinedProps.value.class)
           })
 
-          const classes = configOrCva.__recipe__ ? recipeClass : cvaClass
+          const classes = computed(() => {
+            if (props.unstyled) {
+              const [_htmlProps, _forwardedProps, _variantProps, styleProps, _elementProps] = splittedProps.value
+              const { css: cssStyles, ...propStyles } = styleProps
+              return cx(css(propStyles, cssStyles), combinedProps.value.className, combinedProps.value.class)
+            }
+            return configOrCva.__recipe__ ? recipeClass.value : cvaClass.value
+          })
 
           const vModelProps = computed(() => {
             const result = {};
diff --git a/packages/generator/src/artifacts/vue-jsx/types.ts b/packages/generator/src/artifacts/vue-jsx/types.ts
@@ -29,8 +29,19 @@ export type ComponentProps<T extends ElementType> = T extends IntrinsicElement
   ? Props
   : never
 
+interface Dict {
+  [k: string]: unknown
+}
+
+export interface UnstyledProps {
+  /**
+   * Whether to remove recipe styles
+   */
+  unstyled?: boolean | undefined
+}
+
 export interface ${componentName}<T extends ElementType, P extends Dict = {}> extends FunctionalComponent<
-  JsxHTMLProps<ComponentProps<T>, Assign<JsxStyleProps, P>>
+  JsxHTMLProps<ComponentProps<T> & UnstyledProps, Assign<JsxStyleProps, P>>
 > {}
 
 interface RecipeFn {
@@ -44,7 +55,7 @@ export interface JsxFactoryOptions<TProps extends Dict> {
   forwardProps?: string[]
 }
 
-export type JsxRecipeProps<T extends ElementType, P extends RecipeFn> = JsxHTMLProps<ComponentProps<T>, Assign<JsxStyleProps, P['__type']>>;
+export type JsxRecipeProps<T extends ElementType, P extends RecipeFn> = JsxHTMLProps<ComponentProps<T> & UnstyledProps, Assign<JsxStyleProps, P['__type']>>;
 
 export type JsxElement<T extends ElementType, P> = T extends ${componentName}<infer A, infer B>
   ? ${componentName}<A, Pretty<DistributiveUnion<P, B>>>
@@ -65,7 +76,7 @@ export type JsxElements = {
 
 export type ${upperName} = JsxFactory & JsxElements
 
-export type ${typeName}<T extends ElementType> = JsxHTMLProps<ComponentProps<T>, JsxStyleProps>
+export type ${typeName}<T extends ElementType> = JsxHTMLProps<ComponentProps<T> & UnstyledProps, JsxStyleProps>
 
 export type ${variantName}<T extends ${componentName}<any, any>> = T extends ${componentName}<any, infer Props> ? Props : never
   `,
diff --git a/packages/studio/styled-system/jsx/factory.mjs b/packages/studio/styled-system/jsx/factory.mjs
@@ -23,7 +23,7 @@ function styledFn(Dynamic, configOrCva = {}, options = {}) {
   const __base__ = Dynamic.__base__ || Dynamic
 
   const PandaComponent = /* @__PURE__ */ forwardRef(function PandaComponent(props, ref) {
-    const { as: Element = __base__, children, ...restProps } = props
+    const { as: Element = __base__, unstyled, children, ...restProps } = props
 
     const combinedProps = useMemo(() => Object.assign({}, defaultProps, restProps), [restProps])
 
@@ -43,7 +43,13 @@ function styledFn(Dynamic, configOrCva = {}, options = {}) {
       return cx(css(cvaStyles, propStyles, cssStyles), combinedProps.className)
     }
 
-    const classes = configOrCva.__recipe__ ? recipeClass : cvaClass
+    const classes = () => {
+      if (unstyled) {
+        const { css: cssStyles, ...propStyles } = styleProps
+        return cx(css(propStyles, cssStyles), combinedProps.className)
+      }
+      return configOrCva.__recipe__ ? recipeClass() : cvaClass()
+    }
 
     return createElement(Element, {
       ref,
diff --git a/packages/studio/styled-system/types/jsx.d.ts b/packages/studio/styled-system/types/jsx.d.ts
@@ -7,12 +7,19 @@ interface Dict {
   [k: string]: unknown
 }
 
+export interface UnstyledProps {
+  /**
+   * Whether to remove recipe styles
+   */
+  unstyled?: boolean | undefined
+}
+
 export type ComponentProps<T extends ElementType> = DistributiveOmit<ComponentPropsWithoutRef<T>, 'ref'> & {
   ref?: Ref<ElementRef<T>>
 }
 
 export interface PandaComponent<T extends ElementType, P extends Dict = {}> {
-  (props: JsxHTMLProps<ComponentProps<T>, Assign<JsxStyleProps, P>>): JSX.Element
+  (props: JsxHTMLProps<ComponentProps<T> & UnstyledProps, Assign<JsxStyleProps, P>>): JSX.Element
   displayName?: string
 }
 
@@ -27,7 +34,7 @@ interface JsxFactoryOptions<TProps extends Dict> {
   forwardProps?: string[]
 }
 
-export type JsxRecipeProps<T extends ElementType, P extends Dict> = JsxHTMLProps<ComponentProps<T>, P>;
+export type JsxRecipeProps<T extends ElementType, P extends Dict> = JsxHTMLProps<ComponentProps<T> & UnstyledProps, P>;
 
 export type JsxElement<T extends ElementType, P extends Dict> = T extends PandaComponent<infer A, infer B>
   ? PandaComponent<A, Pretty<DistributiveUnion<P, B>>>
@@ -48,6 +55,6 @@ export type JsxElements = {
 
 export type Panda = JsxFactory & JsxElements
 
-export type HTMLPandaProps<T extends ElementType> = JsxHTMLProps<ComponentProps<T>, JsxStyleProps>
+export type HTMLPandaProps<T extends ElementType> = JsxHTMLProps<ComponentProps<T> & UnstyledProps, JsxStyleProps>
 
 export type PandaVariantProps<T extends PandaComponent<any, any>> = T extends PandaComponent<any, infer Props> ? Props : never
diff --git a/sandbox/preact-ts/src/app.tsx b/sandbox/preact-ts/src/app.tsx
diff --git a/sandbox/remix/app/routes/_index.tsx b/sandbox/remix/app/routes/_index.tsx
diff --git a/website/pages/docs/concepts/style-props.mdx b/website/pages/docs/concepts/style-props.mdx
