feat: add asChild functionality to Box component (#834)

## **Description**

This PR adds `asChild` functionality to the Box component, enabling it
to merge its props onto its immediate child element instead of rendering
a `div`. This enhancement allows developers to apply Box styling and
layout properties to any HTML element while maintaining semantic meaning
and accessibility.

The implementation leverages Radix UI's Slot component to ensure proper
prop merging and ref forwarding, following the same pattern used in the
AvatarBase component.

## **Related issues**

Fixes: <!-- Add issue links if any -->

## **Manual testing steps**

1. Pull and build the branch locally
2. Navigate to the Box component in Storybook
3. View the new "AsChild" story to see the functionality in action
4. Test that Box renders as a div by default (asChild=false)
5. Test that Box renders as its child element when asChild=true
6. Verify that all Box props (padding, margin, flexDirection, etc.) are
properly applied to the child element
7. Test ref forwarding works correctly with asChild=true
8. Verify prop merging works correctly between Box and child element
props
9. Run the test suite to ensure all 5 new asChild tests pass
10. Test accessibility by verifying semantic HTML elements maintain
their native behavior

## **Screenshots/Recordings**

Not applicable - this is a component API enhancement with comprehensive
test coverage.

### **Before**

Box component could only render as a div element.

### **After**

Box component can now render as any HTML element or React component
while preserving all Box styling capabilities.

<img width="1159" height="336" alt="Screenshot 2025-09-17 at 12 27
57 PM"
src="https://github.com/user-attachments/assets/ffb5b4ed-a880-4710-b381-ede2c6d93c8d"
/>

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs)
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-extension/blob/develop/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.

Author: georgewrmarshall

packages/design-system-react/src/components/Box/Box.stories.tsx

@@ -1795,3 +1795,15 @@ export const BackgroundColor: Story = {
     </Box>
   ),
 };
+
+export const AsChild: Story = {
+  render: (args) => (
+    <Box {...args} asChild backgroundColor={BoxBackgroundColor.PrimaryMuted}>
+      <button>
+        <Text asChild>
+          <span>Box rendered as button</span>
+        </Text>
+      </button>
+    </Box>
+  ),
+};

packages/design-system-react/src/components/Box/Box.test.tsx

@@ -561,4 +561,85 @@ describe('Box', () => {
     expect(box).toHaveAttribute('aria-label', 'Test box');
     expect(box.tagName).toBe('DIV');
   });
+
+  it('renders as div by default when asChild is false', () => {
+    render(
+      <Box data-testid="box" asChild={false}>
+        <span>Content</span>
+      </Box>,
+    );
+    const box = screen.getByTestId('box');
+    expect(box.tagName).toBe('DIV');
+  });
+
+  it('renders as child element when asChild is true', () => {
+    render(
+      <Box data-testid="box" asChild padding={4} className="bg-primary-muted">
+        <button type="button">Click me</button>
+      </Box>,
+    );
+    const button = screen.getByTestId('box');
+    expect(button.tagName).toBe('BUTTON');
+    expect(button).toHaveAttribute('type', 'button');
+    expect(button).toHaveClass('bg-primary-muted');
+    expect(button).toHaveClass(TWCLASSMAP_BOX_PADDING[4]);
+    expect(button).toHaveTextContent('Click me');
+  });
+
+  it('forwards ref to child element when asChild is true', () => {
+    const ref = createRef<HTMLDivElement>();
+    render(
+      <Box asChild ref={ref}>
+        <button data-testid="button" type="button">
+          Click me
+        </button>
+      </Box>,
+    );
+
+    const button = screen.getByTestId('button');
+    expect(ref.current).toBe(button);
+    expect(ref.current?.tagName).toBe('BUTTON');
+  });
+
+  it('merges Box props with child element props when asChild is true', () => {
+    render(
+      <Box
+        asChild
+        data-testid="merged-element"
+        padding={2}
+        className="bg-primary-muted"
+        style={{ color: 'red' }}
+      >
+        <div className="bg-error-muted" style={{ backgroundColor: 'blue' }}>
+          Merged content
+        </div>
+      </Box>,
+    );
+
+    const element = screen.getByTestId('merged-element');
+    expect(element.tagName).toBe('DIV');
+    expect(element).toHaveClass('bg-primary-muted');
+    expect(element).toHaveClass('bg-error-muted');
+    expect(element).toHaveClass(TWCLASSMAP_BOX_PADDING[2]);
+    expect(element).toHaveStyle({ color: 'red', backgroundColor: 'blue' });
+  });
+
+  it('applies flex classes to child element when asChild is true and flexDirection is provided', () => {
+    render(
+      <Box
+        asChild
+        data-testid="flex-child"
+        flexDirection={BoxFlexDirection.Column}
+        gap={3}
+      >
+        <section>Flex content</section>
+      </Box>,
+    );
+
+    const section = screen.getByTestId('flex-child');
+    expect(section.tagName).toBe('SECTION');
+    expect(section).toHaveClass('flex');
+    expect(section).toHaveClass(BoxFlexDirection.Column);
+    expect(section).toHaveClass(TWCLASSMAP_BOX_GAP[3]);
+  });
 });

packages/design-system-react/src/components/Box/Box.tsx

@@ -1,3 +1,4 @@
+import { Slot } from '@radix-ui/react-slot';
 import React, { forwardRef } from 'react';
 
 import { twMerge } from '../../utils/tw-merge';
@@ -49,11 +50,14 @@ export const Box = forwardRef<HTMLDivElement, BoxProps>(
       backgroundColor,
       className = '',
       style,
+      asChild,
       children,
       ...props
     }: BoxProps,
     ref,
   ) => {
+    const Component = asChild ? Slot : 'div';
+
     const mergedClassName = twMerge(
       flexDirection ? 'flex' : '',
       flexDirection,
@@ -96,9 +100,9 @@ export const Box = forwardRef<HTMLDivElement, BoxProps>(
     );
 
     return (
-      <div ref={ref} className={mergedClassName} style={style} {...props}>
+      <Component ref={ref} className={mergedClassName} style={style} {...props}>
         {children}
-      </div>
+      </Component>
     );
   },
 );

packages/design-system-react/src/components/Box/Box.types.ts

@@ -120,4 +120,11 @@ export type BoxProps = ComponentProps<'div'> & {
    * Optional prop for additional CSS classes to be applied to the Box component.
    */
   className?: string;
+  /**
+   * Optional boolean that determines if the component should merge its props onto its immediate child
+   * instead of rendering a div element
+   *
+   * @default false
+   */
+  asChild?: boolean;
 };

packages/design-system-react/src/components/Box/README.mdx

@@ -334,6 +334,46 @@ The border width of the component. Uses only valid Tailwind CSS border width val
 
 <Canvas of={BoxStories.BorderWidth} />
 
+### `asChild`
+
+When `true`, the Box component merges its props onto its immediate child element instead of rendering a `div`. This allows you to apply Box styling and layout properties to any HTML element or React component.
+
+The `asChild` prop leverages Radix UI's Slot component to ensure proper prop merging and ref forwarding.
+
+<table>
+  <thead>
+    <tr>
+      <th align="left">TYPE</th>
+      <th align="left">REQUIRED</th>
+      <th align="left">DEFAULT</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td align="left">
+        <code>boolean</code>
+      </td>
+      <td align="left">No</td>
+      <td align="left">
+        <code>false</code>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+```tsx
+// Box as button (renders as button with Box styling)
+<Box asChild backgroundColor={BoxBackgroundColor.PrimaryMuted}>
+  <button>
+    <Text asChild>
+      <span>Box rendered as button</span>
+    </Text>
+  </button>
+</Box>
+```
+
+<Canvas of={BoxStories.AsChild} />
+
 ### `className`
 
 Use the `className` prop to add custom CSS classes to the component. These classes will be merged with the component's default classes using `twMerge`, allowing you to: