# LinkStyledAsButton

> Slug: `link-styled-as-button` · Category: Actions

## When to use
- A control that visually looks like a `Button` but actually navigates (renders an `<a>`). Examples: "Shop deals", "View account".
- Cross-page CTAs in marketing or transactional surfaces.
- Buttons that benefit from native browser link behaviors (right-click open in new tab, preview).

## When NOT to use
- The action is in-page (no URL) — use `Button`.
- Inline link inside copy — use `Link`.
- Icon-only — use `IconButton` (or anchor-wrapped `Avatar`).

## Variants & decision tree
- Same emphasis levels as `Button`: `variant="primary" | "secondary" | "tertiary"`.
- For tertiary, pass `trailingDecoration` to render a forward chevron decoration.
- Optional `leadingDecoration` renders before the label for any variant.
- Sizes: `large`, `small`, `xs`.

## States
- `disabled` -> `aria-disabled` (anchor stays in tab order; consumer is responsible for blocking navigation since anchors don't support native disabled).
- Inverse via theme or `inverse` prop.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`label`** | `ReactNode` | — | Visible label (rendered inside a `<span>`). |
| `variant` | `'primary' \| 'secondary' \| 'tertiary'` | `'primary'` | Emphasis variant. |
| `size` | `'large' \| 'small' \| 'xs'` | `'large'` | Sets `data-size`. |
| `leadingDecoration` | `ReactNode` | — | Leading SVG element. |
| `trailingDecoration` | `ReactNode` | — | Trailing SVG element (only renders for tertiary). |
| `monochrome` | `boolean` | `false` | Neutral palette. |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `disabled` | `boolean` | `false` | Sets `aria-disabled`. |
| `a11yLabel` | `string` | — | Override accessible name. |
| `describedBy` | `string` | — | `aria-describedby`. |
| `href` | `string` | — | Navigation target (standard anchor prop). |

## Usage examples
```tsx
import { LinkStyledAsButton } from 'arrow-react-bootstrap';

// Primary CTA that navigates
<LinkStyledAsButton href="/checkout" label="Go to checkout" />

// Secondary external link
<LinkStyledAsButton variant="secondary" href="https://help.example.com" label="Get help" target="_blank" rel="noopener noreferrer" />

// Tertiary with forward chevron
<LinkStyledAsButton
  variant="tertiary"
  href="/learn-more"
  label="Learn more"
  trailingDecoration={<svg viewBox="0 0 24 24"><path d="M9 6l6 6-6 6"/></svg>}
/>
```

## Composition
- Mix with `Button` inside `ButtonGroup` or `ButtonTray` when a CTA pair includes one navigation and one in-page action.
- Use inside marketing `PromoBanner` content slots, hero sections, and `Tile` calls-to-action.

## Accessibility
- Renders a real `<a>`, so screen readers announce it as a link, not a button.
- Provide `a11yLabel` when the visible text needs disambiguation.
- For external links, set `target="_blank"` with `rel="noopener noreferrer"` and consider adding context to the label ("Open in new tab").

## Do / Don't
- Do: prefer this over `Button` whenever an `href` is available.
- Do: use `trailingDecoration` only with `variant="tertiary"`.
- Don't: simulate navigation with `onClick`; pass an `href`.
- Don't: omit `href` — anchors without href are not focusable.
