Using React-Bootstrap's `as` Prop: Swap Elements Without Losing Bootstrap Styling

The Problem: Semantic HTML vs Styled Components

When building React applications with React-Bootstrap, you often need components that look like Bootstrap elements but render as different HTML tags. A button that should behave like a navigation link is a common scenario. Using a <button> for navigation breaks browser features like middle-click to open in a new tab, while an <a> without proper styling loses Bootstrap's button appearance.

The Solution: The `as` Prop

React-Bootstrap solves this with the as prop, which swaps the rendered element while preserving Bootstrap classes, variants, and internal wiring. The component renders the specified element type as the root, then forwards className, event handlers, and relevant props.

Basic Configuration Example

Here's how to render a button that looks like a Bootstrap button but functions as a navigation link:

import { Button } from 'react-bootstrap';
import { Link } from 'react-router-dom';

// Renders as an anchor tag with button styling
<Button as={Link} to="/reports" variant="primary">
  View Reports
</Button>

// Alternative with plain HTML anchor
<Button as="a" variant="primary" href="/reports" target="_blank" rel="noopener">
  Open Reports
</Button>

How It Works

The as prop accepts any valid React element type—a string tag like 'a' or 'div', or a component like React Router's Link. React-Bootstrap renders this as the root element and applies its internal logic on top. Since Bootstrap's .btn class is element-agnostic, an anchor with .btn and .btn-primary maintains button styling while keeping proper link semantics.

Common Use Cases

• Navigation Links: <Button as={Link} to="/path"> for SPA navigation
• External Links: <Button as="a" href="url" target="_blank"> for downloads
• Semantic Markup: <Card as="article"> for proper document structure
• List Items: <ListGroup.Item as="li"> for correct nesting

Important Limitations

The as prop only changes the root element—it does not modify styling scope or component behavior. Props must be valid for the target element. For example, Nav.Link and Breadcrumb.Item render anchors by default and expect href and active props.

TypeScript Considerations

React-Bootstrap's TypeScript types for as are permissive (ElementType), so invalid prop combinations may compile but fail at runtime. Always verify that props make sense for the element you're rendering to.

Common Mistakes to Avoid

1. Ref Forwarding: Custom components passed to as must forward refs via React.forwardRef. Overlay-based components like Tooltip, Popover, and Dropdown will fail to position correctly without proper ref forwarding.
2. Keyboard Semantics: Using as="div" with onClick on interactive components drops keyboard activation. Add role="button", tabIndex="0", and handle onKeyDown for Enter/Space.
3. Disabled State on Anchors: The disabled prop on an anchor element only applies styling and aria-disabled—there's no native disabled attribute. Handle click events to prevent navigation when disabled.

Version Compatibility

The as prop behaves consistently across React-Bootstrap v1 (Bootstrap 4) and v2 (Bootstrap 5), but underlying class names differ. For example, v1's custom-control and form-row don't exist in v2. Upgrading may change the styling produced by as-rendered markup even though the prop's mechanics remain the same.

Verification Checklist

1. Inspect the DOM in browser devtools—the root node should be the as target with expected Bootstrap classes
2. Check the official React-Bootstrap documentation for the as prop entry and its stated type
3. Test keyboard activation, focus order, and screen-reader output for non-standard elements
4. Confirm your React-Bootstrap major version (v1 vs v2) and Bootstrap CSS version in use

Best Practices Summary

• Use as for semantic correctness, not visual customization—prefer variant, size, or bsPrefix for styling
• Always verify props are valid for the target element type
• Ensure custom components forward refs properly
• Test interactive behavior including keyboard navigation