[useRender] Add defaultTagName parameter (mui#2527)

Author: atomiks

docs/reference/generated/use-render.json

@@ -4,7 +4,6 @@
   "parameters": {
     "render": {
       "type": "useRender.RenderProp<Record<string, unknown>>",
-      "required": true,
       "description": "The React element or a function that returns one to override the default element."
     },
     "ref": {
@@ -33,6 +32,12 @@
       "default": "true",
       "description": "If `false`, the hook will skip most of its internal logic and return `null`.\nThis is useful for rendering a component conditionally.",
       "detailedType": "boolean | undefined | undefined"
+    },
+    "defaultTagName": {
+      "type": "'symbol' | 'object' | 'a' | 'abbr' | 'address' | 'area' | 'article' | 'aside' | 'audio' | 'b' | 'base' | 'bdi' | 'bdo' | 'big' | 'blockquote' | 'body' | 'br' | 'button' | 'canvas' | 'caption' | 'center' | 'cite' | 'code' | 'col' | 'colgroup' | 'data' | 'datalist' | 'dd' | 'del' | 'details' | 'dfn' | 'dialog' | 'div' | 'dl' | 'dt' | 'em' | 'embed' | 'fieldset' | 'figcaption' | 'figure' | 'footer' | 'form' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'head' | 'header' | 'hgroup' | 'hr' | 'html' | 'i' | 'iframe' | 'img' | 'input' | 'ins' | 'kbd' | 'keygen' | 'label' | 'legend' | 'li' | 'link' | 'main' | 'map' | 'mark' | 'menu' | 'menuitem' | 'meta' | 'meter' | 'nav' | 'noindex' | 'noscript' | 'ol' | 'optgroup' | 'option' | 'output' | 'p' | 'param' | 'picture' | 'pre' | 'progress' | 'q' | 'rp' | 'rt' | 'ruby' | 's' | 'samp' | 'search' | 'slot' | 'script' | 'section' | 'select' | 'small' | 'source' | 'span' | 'strong' | 'style' | 'sub' | 'summary' | 'sup' | 'table' | 'template' | 'tbody' | 'td' | 'textarea' | 'tfoot' | 'th' | 'thead' | 'time' | 'title' | 'tr' | 'track' | 'u' | 'ul' | 'var' | 'video' | 'wbr' | 'webview' | 'svg' | 'animate' | 'animateMotion' | 'animateTransform' | 'circle' | 'clipPath' | 'defs' | 'desc' | 'ellipse' | 'feBlend' | 'feColorMatrix' | 'feComponentTransfer' | 'feComposite' | 'feConvolveMatrix' | 'feDiffuseLighting' | 'feDisplacementMap' | 'feDistantLight' | 'feDropShadow' | 'feFlood' | 'feFuncA' | 'feFuncB' | 'feFuncG' | 'feFuncR' | 'feGaussianBlur' | 'feImage' | 'feMerge' | 'feMergeNode' | 'feMorphology' | 'feOffset' | 'fePointLight' | 'feSpecularLighting' | 'feSpotLight' | 'feTile' | 'feTurbulence' | 'filter' | 'foreignObject' | 'g' | 'image' | 'line' | 'linearGradient' | 'marker' | 'mask' | 'metadata' | 'mpath' | 'path' | 'pattern' | 'polygon' | 'polyline' | 'radialGradient' | 'rect' | 'set' | 'stop' | 'switch' | 'text' | 'textPath' | 'tspan' | 'use' | 'view'",
+      "default": "'div'",
+      "description": "The default tag name to use for the rendered element when `render` is not provided.",
+      "detailedType": "| 'symbol'\n| 'object'\n| 'a'\n| 'abbr'\n| 'address'\n| 'area'\n| 'article'\n| 'aside'\n| 'audio'\n| 'b'\n| 'base'\n| 'bdi'\n| 'bdo'\n| 'big'\n| 'blockquote'\n| 'body'\n| 'br'\n| 'button'\n| 'canvas'\n| 'caption'\n| 'center'\n| 'cite'\n| 'code'\n| 'col'\n| 'colgroup'\n| 'data'\n| 'datalist'\n| 'dd'\n| 'del'\n| 'details'\n| 'dfn'\n| 'dialog'\n| 'div'\n| 'dl'\n| 'dt'\n| 'em'\n| 'embed'\n| 'fieldset'\n| 'figcaption'\n| 'figure'\n| 'footer'\n| 'form'\n| 'h1'\n| 'h2'\n| 'h3'\n| 'h4'\n| 'h5'\n| 'h6'\n| 'head'\n| 'header'\n| 'hgroup'\n| 'hr'\n| 'html'\n| 'i'\n| 'iframe'\n| 'img'\n| 'input'\n| 'ins'\n| 'kbd'\n| 'keygen'\n| 'label'\n| 'legend'\n| 'li'\n| 'link'\n| 'main'\n| 'map'\n| 'mark'\n| 'menu'\n| 'menuitem'\n| 'meta'\n| 'meter'\n| 'nav'\n| 'noindex'\n| 'noscript'\n| 'ol'\n| 'optgroup'\n| 'option'\n| 'output'\n| 'p'\n| 'param'\n| 'picture'\n| 'pre'\n| 'progress'\n| 'q'\n| 'rp'\n| 'rt'\n| 'ruby'\n| 's'\n| 'samp'\n| 'search'\n| 'slot'\n| 'script'\n| 'section'\n| 'select'\n| 'small'\n| 'source'\n| 'span'\n| 'strong'\n| 'style'\n| 'sub'\n| 'summary'\n| 'sup'\n| 'table'\n| 'template'\n| 'tbody'\n| 'td'\n| 'textarea'\n| 'tfoot'\n| 'th'\n| 'thead'\n| 'time'\n| 'title'\n| 'tr'\n| 'track'\n| 'u'\n| 'ul'\n| 'var'\n| 'video'\n| 'wbr'\n| 'webview'\n| 'svg'\n| 'animate'\n| 'animateMotion'\n| 'animateTransform'\n| 'circle'\n| 'clipPath'\n| 'defs'\n| 'desc'\n| 'ellipse'\n| 'feBlend'\n| 'feColorMatrix'\n| 'feComponentTransfer'\n| 'feComposite'\n| 'feConvolveMatrix'\n| 'feDiffuseLighting'\n| 'feDisplacementMap'\n| 'feDistantLight'\n| 'feDropShadow'\n| 'feFlood'\n| 'feFuncA'\n| 'feFuncB'\n| 'feFuncG'\n| 'feFuncR'\n| 'feGaussianBlur'\n| 'feImage'\n| 'feMerge'\n| 'feMergeNode'\n| 'feMorphology'\n| 'feOffset'\n| 'fePointLight'\n| 'feSpecularLighting'\n| 'feSpotLight'\n| 'feTile'\n| 'feTurbulence'\n| 'filter'\n| 'foreignObject'\n| 'g'\n| 'image'\n| 'line'\n| 'linearGradient'\n| 'marker'\n| 'mask'\n| 'metadata'\n| 'mpath'\n| 'path'\n| 'pattern'\n| 'polygon'\n| 'polyline'\n| 'radialGradient'\n| 'rect'\n| 'set'\n| 'stop'\n| 'switch'\n| 'text'\n| 'textPath'\n| 'tspan'\n| 'use'\n| 'view'\n| undefined"
     }
   },
   "returnValue": "ReactElement | null"

docs/src/app/(public)/(content)/react/utils/use-render/demos/render-callback/css-modules/index.tsx

@@ -11,7 +11,7 @@ interface CounterState {
 interface CounterProps extends useRender.ComponentProps<'button', CounterState> {}
 
 function Counter(props: CounterProps) {
-  const { render = <button />, ...otherProps } = props;
+  const { render, ...otherProps } = props;
 
   const [count, setCount] = React.useState(0);
   const odd = count % 2 === 1;
@@ -32,6 +32,7 @@ function Counter(props: CounterProps) {
   };
 
   const element = useRender({
+    defaultTagName: 'button',
     render,
     state,
     props: mergeProps<'button'>(defaultProps, otherProps),

docs/src/app/(public)/(content)/react/utils/use-render/demos/render/css-modules/index.tsx

@@ -7,9 +7,10 @@ import styles from './index.module.css';
 interface TextProps extends useRender.ComponentProps<'p'> {}
 
 function Text(props: TextProps) {
-  const { render = <p />, ...otherProps } = props;
+  const { render, ...otherProps } = props;
 
   const element = useRender({
+    defaultTagName: 'p',
     render,
     props: mergeProps<'p'>({ className: styles.Text }, otherProps),
   });

docs/src/app/(public)/(content)/react/utils/use-render/page.mdx

@@ -31,6 +31,11 @@ The `useRender` hook lets you build custom components that provide a `render` pr
       description:
         'The state of the component. It will be used as a parameter for the render callback.',
     },
+    defaultTagName: {
+      type: 'keyof React.JSX.IntrinsicElements',
+      description:
+        'The default tag name to use for the rendered element when `render` is not provided.',
+    },
   }}
 />
 
@@ -97,11 +102,12 @@ When building custom components, you often need to control a ref internally whil
 
 In React 19, `React.forwardRef()` is not needed when building primitive components, as the external ref prop is already contained inside `props`. Your internal ref can be passed to `ref` to be merged with `props.ref`:
 
-```tsx title="React 19" {5} "internalRef"
-function Text({ render = <p />, ...props }: TextProps) {
+```tsx title="React 19" {6} "internalRef"
+function Text({ render, ...props }: TextProps) {
   const internalRef = React.useRef<HTMLElement | null>(null);
 
   const element = useRender({
+    defaultTagName: 'p',
     ref: internalRef,
     props,
     render,
@@ -115,14 +121,15 @@ In older versions of React, you need to use `React.forwardRef()` and add the for
 
 The [examples](#examples) above assume React 19, and should be modified to use `React.forwardRef()` to support React 18 and 17.
 
-```tsx title="React 18 and 17" {8} "forwardedRef" "internalRef"
+```tsx title="React 18 and 17" {9} "forwardedRef" "internalRef"
 const Text = React.forwardRef(function Text(
-  { render = <p />, ...props }: TextProps,
+  { render, ...props }: TextProps,
   forwardedRef: React.ForwardedRef<HTMLElement>,
 ) {
   const internalRef = React.useRef<HTMLElement | null>(null);
 
   const element = useRender({
+    defaultTagName: 'p',
     ref: [forwardedRef, internalRef],
     props,
     render,
@@ -142,14 +149,15 @@ To type props, there are two interfaces:
 ```tsx title="Typing props" {1,4}
 interface ButtonProps extends useRender.ComponentProps<'button'> {}
 
-function Button({ render = <button />, ...props }: ButtonProps) {
+function Button({ render, ...props }: ButtonProps) {
   const defaultProps: useRender.ElementProps<'button'> = {
     className: styles.Button,
     type: 'button',
     children: 'Click me',
   };
 
   const element = useRender({
+    defaultTagName: 'button',
     render,
     props: mergeProps<'button'>(defaultProps, props),
   });
@@ -183,10 +191,14 @@ In Base UI, `useRender` lets you implement a `render` prop. The example below is
 ```jsx title="Base UI render prop"
 import { useRender } from '@base-ui-components/react/use-render';
 
-function Button({ render = <button />, ...props }) {
-  return useRender({ render, props });
+function Button({ render, ...props }) {
+  return useRender({
+    defaultTagName: 'button',
+    render,
+    props,
+  });
 }
 
 // Usage
-<Button render={<a href="/contact">Contact</a>} />;
+<Button render={<a href="/contact" />}>Contact</Button>;
 ```

packages/react/src/use-render/useRender.test.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { expect } from 'chai';
-import { createRenderer } from '@mui/internal-test-utils';
 import { useRender } from '@base-ui-components/react/use-render';
+import { createRenderer } from '#test-utils';
 
 describe('useRender', () => {
   const { render } = createRenderer();
@@ -70,6 +70,44 @@ describe('useRender', () => {
     });
   });
 
+  describe('param: defaultTagName', () => {
+    it('renders the element with the default tag with no render prop', async () => {
+      function TestComponent({
+        defaultTagName,
+      }: {
+        defaultTagName: keyof React.JSX.IntrinsicElements;
+      }) {
+        return useRender({ defaultTagName });
+      }
+
+      const { container, setProps } = await render(<TestComponent defaultTagName="div" />);
+      expect(container.firstElementChild).to.have.property('tagName', 'DIV');
+
+      await setProps({ defaultTagName: 'span' });
+      expect(container.firstElementChild).to.have.property('tagName', 'SPAN');
+    });
+
+    it('is overwritten by the render prop', async () => {
+      function TestComponent({
+        render: renderProp,
+        defaultTagName,
+      }: {
+        render: useRender.Parameters<{}, Element, undefined>['render'];
+        defaultTagName: keyof React.JSX.IntrinsicElements;
+      }) {
+        return useRender({ render: renderProp, defaultTagName });
+      }
+
+      const { container, setProps } = await render(
+        <TestComponent defaultTagName="div" render={<span />} />,
+      );
+      expect(container.firstElementChild).to.have.property('tagName', 'SPAN');
+
+      await setProps({ defaultTagName: 'a' });
+      expect(container.firstElementChild).to.have.property('tagName', 'SPAN');
+    });
+  });
+
   describe('state to data attributes', () => {
     it('converts state to data attributes automatically', async () => {
       function TestComponent() {

packages/react/src/use-render/useRender.ts

@@ -22,7 +22,7 @@ export function useRender<
 
   renderParams.customStyleHookMapping = renderParams.stateAttributesMapping;
 
-  return useRenderElement(undefined, renderParams, renderParams);
+  return useRenderElement(renderParams.defaultTagName, renderParams, renderParams);
 }
 
 export namespace useRender {
@@ -57,7 +57,7 @@ export namespace useRender {
     /**
      * The React element or a function that returns one to override the default element.
      */
-    render: RenderProp<State>;
+    render?: RenderProp<State>;
     /**
      * The ref to apply to the rendered element.
      */
@@ -86,6 +86,11 @@ export namespace useRender {
      * @default true
      */
     enabled?: Enabled;
+    /**
+     * The default tag name to use for the rendered element when `render` is not provided.
+     * @default 'div'
+     */
+    defaultTagName?: keyof React.JSX.IntrinsicElements;
   }
 
   export type ReturnValue<Enabled extends boolean | undefined> = Enabled extends false