refactor: replace as prop with render prop in Text and Headline (#740)

* refactor: replace `as` prop with `render` prop in Text and Headline

Migrate Text and Headline components from the brittle `as` polymorphic
prop pattern to Base UI's `render` prop + `useRender` hook, matching
the pattern already used by the Flex component. This eliminates manual
type unions, removes a `@ts-expect-error` suppression, and enables
rendering as any element via JSX or render functions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: fix render prop playground controls to use JSX element syntax

The render prop accepts ReactElement values, not strings. Update
playground select options to use JSX element strings (e.g. '<h2 />')
so getPropsString generates correct `render={<h2 />}` syntax.
Also document the render prop in Headline's API Reference section.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: update V1 migration guide for Text and Headline render prop

Add migration documentation for the breaking change where `as` prop is
replaced by `render` on Text and Headline components. Includes
before/after examples, TypeScript type change notes, and render function
usage. Updates Table of Contents, cross-cutting changes note, and
Migration Checklist.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rohanchkrabrty

apps/www/src/components/playground/headline-examples.tsx

@@ -8,13 +8,13 @@ export function HeadlineExamples() {
     <PlaygroundLayout title='Headline'>
       <Flex direction='column' gap='large'>
         <Flex direction='column' gap='large'>
-          <Headline size='large' as='h1'>
+          <Headline size='large' render={<h1 />}>
             Large Headline
           </Headline>
 
           <Headline size='medium'>Medium Headline</Headline>
 
-          <Headline size='small' as='h3'>
+          <Headline size='small' render={<h3 />}>
             Small Headline
           </Headline>
         </Flex>

apps/www/src/content/docs/components/headline/demo.ts

@@ -20,10 +20,10 @@ export const playground = {
       options: ['regular', 'medium'],
       defaultValue: 'medium'
     },
-    as: {
+    render: {
       type: 'select',
-      options: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
-      defaultValue: 'h2'
+      options: ['<h1 />', '<h2 />', '<h3 />', '<h4 />', '<h5 />', '<h6 />'],
+      defaultValue: '<h2 />'
     },
     align: {
       type: 'select',

apps/www/src/content/docs/components/headline/index.mdx

@@ -20,7 +20,7 @@ import { Headline } from '@raystack/apsara'
 
 ## API Reference
 
-Renders a heading element with configurable size and weight.
+Renders a heading element with configurable size and weight. Use the `render` prop to change the heading level or provide a custom render function.
 
 <auto-type-table path="./props.ts" name="HeadlineProps" />
 

apps/www/src/content/docs/components/headline/props.ts

@@ -12,10 +12,13 @@ export interface HeadlineProps {
   weight?: 'regular' | 'medium';
 
   /**
-   * HTML heading element to render.
+   * Custom render element or function. Accepts a JSX element (e.g. `<h1 />`)
+   * or a render function for full control.
    * @default "h2"
    */
-  as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+  render?:
+    | React.ReactElement
+    | ((props: React.ComponentPropsWithRef<'h2'>) => React.ReactElement);
 
   /**
    * Text alignment.

apps/www/src/content/docs/components/text/demo.ts

@@ -23,10 +23,10 @@ export const playground = {
       ],
       defaultValue: 'primary'
     },
-    as: {
+    render: {
       type: 'select',
-      options: ['span', 'p', 'div', 'label', 'a'],
-      defaultValue: 'span'
+      options: ['<span />', '<p />', '<div />', '<label />', '<a />'],
+      defaultValue: '<span />'
     },
     size: {
       type: 'select',

apps/www/src/content/docs/components/text/index.mdx

@@ -29,7 +29,7 @@ import { Text } from '@raystack/apsara'
 
 ## API Reference
 
-According to the element rendered using `as`, Text will extend over the default HTML Attributes
+Use the `render` prop to change the rendered element or provide a custom render function.
 
 <auto-type-table path="./props.ts" name="TextProps" />
 

apps/www/src/content/docs/components/text/props.ts

@@ -1,9 +1,12 @@
 export interface TextProps {
   /**
-   * Text element to render as.
+   * Custom render element or function. Accepts a JSX element (e.g. `<p />`)
+   * or a render function for full control.
    * @default "span"
    */
-  as?: 'span' | 'p' | 'div' | 'label' | 'a';
+  render?:
+    | React.ReactElement
+    | ((props: React.ComponentPropsWithRef<'span'>) => React.ReactElement);
 
   /**
    * The visual style variant.

docs/V1-migration.md

@@ -32,6 +32,7 @@ This guide covers all breaking changes when upgrading from the last stable Radix
       - [New Features](#new-features-2)
     - [Flex](#flex)
     - [Grid](#grid)
+    - [Headline](#headline)
     - [InputField](#inputfield)
     - [Popover](#popover)
       - [New Features](#new-features-3)
@@ -49,6 +50,7 @@ This guide covers all breaking changes when upgrading from the last stable Radix
     - [Switch](#switch)
     - [Tabs](#tabs)
       - [New Features](#new-features-8)
+    - [Text](#text)
     - [TextArea](#textarea)
     - [Toast](#toast)
       - [New Features](#new-features-9)
@@ -110,6 +112,8 @@ Radix's `asChild` composition pattern is gone. Use the `render` prop instead. No
 
 Affected components: Button, Grid, Grid.Item, Popover.Trigger, Menu.Trigger, Drawer.Trigger, Dialog.Trigger, Dialog.Close, AlertDialog.Trigger, Breadcrumb.Item, Tooltip.Trigger.
 
+> **Note:** Text and Headline also replace their `as` prop with `render`, but using a different pattern. Instead of `asChild` (which forwarded all props to a child element), `as` was a simple string tag name. The new `render` prop accepts a JSX element or a render function, matching the Base UI convention. See [Text](#text) and [Headline](#headline) for details.
+
 ### Callback Signatures
 
 Most `onValueChange`, `onOpenChange`, and `onCheckedChange` callbacks now receive an optional second `eventDetails` argument:
@@ -767,6 +771,35 @@ Type changed to `useRender.ComponentProps<'div'>` -- may cause TypeScript errors
 
 ---
 
+### Headline
+
+**`as` prop replaced by `render`:**
+
+The `as` prop accepted a string tag name (`'h1'` through `'h6'`). The new `render` prop accepts a JSX element or a render function, consistent with the Base UI pattern used across the library. The default element remains `<h2>`.
+
+```tsx
+// Before
+<Headline as="h1" size="large">Page Title</Headline>
+<Headline as="h3" size="small">Section Title</Headline>
+<Headline>Default h2</Headline>
+
+// After
+<Headline render={<h1 />} size="large">Page Title</Headline>
+<Headline render={<h3 />} size="small">Section Title</Headline>
+<Headline>Default h2</Headline>
+```
+
+The `render` prop also supports render functions for full control:
+
+```tsx
+// Render function for custom element
+<Headline render={props => <h1 {...props} />}>Page Title</Headline>
+```
+
+**TypeScript:** The type changed from `HeadlineBaseProps & ComponentProps<'h1'> & { as?: 'h1' | ... | 'h6' }` to `HeadlineBaseProps & useRender.ComponentProps<'h2'>`. If you explicitly typed Headline props, update to `HeadlineProps` (now exported).
+
+---
+
 ### InputField
 
 **Label, helper text, error, and optional indicator moved to `Field` wrapper.** InputField is now a pure input control — wrap it with the new `Field` component for labels, descriptions, and error messages.
@@ -1283,6 +1316,49 @@ Key changes:
 
 ---
 
+### Text
+
+**`as` prop replaced by `render`:**
+
+The `as` prop accepted a string tag name (`'span'`, `'p'`, `'div'`, `'label'`, `'a'`). The new `render` prop accepts a JSX element or a render function, consistent with the Base UI pattern used across the library. The default element remains `<span>`.
+
+```tsx
+// Before
+<Text as="label">Username</Text>
+<Text as="p">Paragraph text</Text>
+<Text as="a" href="/link">Click here</Text>
+<Text>Default span</Text>
+
+// After
+<Text render={<label />}>Username</Text>
+<Text render={<p />}>Paragraph text</Text>
+<Text render={<a href="/link" />}>Click here</Text>
+<Text>Default span</Text>
+```
+
+Note that HTML attributes specific to the rendered element (like `href` for anchors, `htmlFor` for labels) now go on the JSX element inside `render`, not on `Text` itself:
+
+```tsx
+// Before
+<Text as="label" htmlFor="email-input">Email</Text>
+<Text as="a" href="#section" target="_blank">Link</Text>
+
+// After
+<Text render={<label htmlFor="email-input" />}>Email</Text>
+<Text render={<a href="#section" target="_blank" />}>Link</Text>
+```
+
+The `render` prop also supports render functions for full control:
+
+```tsx
+// Render function for any element
+<Text render={props => <section {...props} />}>Custom element</Text>
+```
+
+**TypeScript:** The type changed from a discriminated union (`TextSpanProps | TextDivProps | TextLabelProps | TextPProps | TextAProps`) to `TextBaseProps & useRender.ComponentProps<'span'>`. The `render` prop now accepts any element, so you are no longer limited to the five original tag names. The `// @ts-expect-error` that was needed internally for polymorphic refs is also gone.
+
+---
+
 ### TextArea
 
 **Label, helper text, error, and optional indicator moved to `Field` wrapper.** TextArea is now a pure textarea control — wrap it with the new `Field` component for labels, descriptions, and error messages.
@@ -1596,6 +1672,8 @@ These are purely additive -- no migration needed.
 - [ ] Upgrade to React 19
 - [ ] Update CSS import order (`normalize.css` before `style.css`)
 - [ ] Global find-and-replace: `asChild` -> `render` prop pattern
+- [ ] Replace `Text as="..."` with `Text render={<element />}` (see [Text](#text))
+- [ ] Replace `Headline as="..."` with `Headline render={<element />}` (see [Headline](#headline))
 - [ ] Update callback signatures where TypeScript complains
 - [ ] Replace `DropdownMenu` imports with `Menu`
 - [ ] Replace `Sheet` imports with `Drawer`

packages/raystack/components/headline/__tests__/headline.test.tsx

@@ -30,20 +30,48 @@ describe('Headline', () => {
     });
   });
 
-  describe('As Prop', () => {
-    const headingLevels = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] as const;
+  describe('Render Prop', () => {
+    it('renders as h1 via render prop', () => {
+      render(<Headline render={<h1 />}>Heading</Headline>);
+      const heading = screen.getByText('Heading');
+      expect(heading.tagName).toBe('H1');
+    });
+
+    it('renders as h3 via render prop', () => {
+      render(<Headline render={<h3 />}>Heading</Headline>);
+      const heading = screen.getByText('Heading');
+      expect(heading.tagName).toBe('H3');
+    });
+
+    it('renders as h4 via render prop', () => {
+      render(<Headline render={<h4 />}>Heading</Headline>);
+      const heading = screen.getByText('Heading');
+      expect(heading.tagName).toBe('H4');
+    });
+
+    it('renders as h5 via render prop', () => {
+      render(<Headline render={<h5 />}>Heading</Headline>);
+      const heading = screen.getByText('Heading');
+      expect(heading.tagName).toBe('H5');
+    });
 
-    it.each(headingLevels)('renders as %s element', level => {
-      render(<Headline as={level}>Heading</Headline>);
+    it('renders as h6 via render prop', () => {
+      render(<Headline render={<h6 />}>Heading</Headline>);
       const heading = screen.getByText('Heading');
-      expect(heading.tagName).toBe(level.toUpperCase());
+      expect(heading.tagName).toBe('H6');
     });
 
     it('renders as h2 by default', () => {
       render(<Headline>Heading</Headline>);
       const heading = screen.getByText('Heading');
       expect(heading.tagName).toBe('H2');
     });
+
+    it('supports render function', () => {
+      render(<Headline render={props => <h1 {...props} />}>Heading</Headline>);
+      const heading = screen.getByText('Heading');
+      expect(heading.tagName).toBe('H1');
+    });
   });
 
   describe('Sizes', () => {

packages/raystack/components/headline/headline.tsx

@@ -1,5 +1,5 @@
+import { mergeProps, useRender } from '@base-ui/react';
 import { cva, type VariantProps } from 'class-variance-authority';
-import { ComponentProps } from 'react';
 import styles from './headline.module.css';
 
 const headline = cva(styles.headline, {
@@ -41,26 +41,29 @@ export type HeadlineBaseProps = VariantProps<typeof headline> & {
   size?: 't1' | 't2' | 't3' | 't4' | 'small' | 'medium' | 'large';
 };
 
-type HeadlineProps = HeadlineBaseProps &
-  ComponentProps<'h1'> & {
-    as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
-  };
+export type HeadlineProps = HeadlineBaseProps & useRender.ComponentProps<'h2'>;
 
 export function Headline({
   className,
   size,
   weight,
   align,
   truncate,
-  as: Component = 'h2',
+  render,
+  ref,
   ...props
 }: HeadlineProps) {
-  return (
-    <Component
-      className={headline({ size, weight, align, truncate, className })}
-      {...props}
-    />
-  );
+  const element = useRender({
+    defaultTagName: 'h2',
+    ref,
+    render,
+    props: mergeProps<'h2'>(
+      { className: headline({ size, weight, align, truncate, className }) },
+      props
+    )
+  });
+
+  return element;
 }
 
 Headline.displayName = 'Headline';