# Admonition

A callout component for highlighting important information, warnings, errors, or success messages. Supports multiple color variants and an optional call-to-action button.

```tsx demo
import { Admonition } from "@tenstorrent/vesper/admonition";

export default function AdmonitionDemo() {
  return (
    <Admonition variant="info">This is an informational admonition.</Admonition>
  );
}
```

## Options

| Prop       | Type                                                          | Description                                                                       | Default    |
| ---------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------- |
| `size`     | `"sm" \| "md"`                                                | The size of the admonition. Affects padding and typography.                       | `"md"`     |
| `variant`  | `"info" \| "success" \| "warning" \| "danger" \| "secondary"` | The visual variant, which determines color scheme and icon.                       | `"info"`   |
| `subtle`   | `boolean`                                                     | When `true`, renders the admonition with a more subdued appearance.               | `false`    |
| `cta`      | `ButtonProps`                                                 | Props passed to an optional call-to-action button rendered alongside the content. | —          |
| `ctaAs`    | `ElementType`                                                 | The element type the CTA will render as.                                          | `"button"` |
| `children` | `ReactNode`                                                   | The content displayed inside the admonition.                                      | —          |

You may also pass additional props to the underlying element. For example, you may wish to give the `<Admonition>` instance a custom max-width, aria-label, etc.

## Examples

### Info variant (default)

An `Admonition` renders with the `info` variant at `md` size when no `variant` or `size` prop is specified:

```tsx demo
import { Admonition } from "@tenstorrent/vesper/admonition";

export default function BasicAdmonition() {
  return <Admonition>Helpful information goes here.</Admonition>;
}
```

### Warning variant, `sm` size

Use the `warning` variant to flag content that needs attention, and `size="sm"` to give it less padding and smaller typography:

```tsx demo
import { Admonition } from "@tenstorrent/vesper/admonition";

export default function WarningAdmonition() {
  return (
    <Admonition variant="warning" size="sm">
      Please review before continuing.
    </Admonition>
  );
}
```

### Danger variant, with CTA

The `danger` variant highlights destructive or error states, and the `cta` prop renders a call-to-action button alongside the content:

```tsx demo
import { Admonition } from "@tenstorrent/vesper/admonition";

export default function DangerAdmonition() {
  return (
    <Admonition
      variant="danger"
      cta={{ children: "Undo", onClick: () => console.log("Undo") }}
    >
      This action cannot be reversed.
    </Admonition>
  );
}
```

### Success variant

The `success` variant is best suited for confirming an action completed as expected:

```tsx demo
import { Admonition } from "@tenstorrent/vesper/admonition";

export default function SuccessAdmonition() {
  return (
    <Admonition variant="success">Operation completed successfully.</Admonition>
  );
}
```

### Secondary variant

The `secondary` variant provides a neutral color scheme for supplementary information that doesn't need to stand out:

```tsx demo
import { Admonition } from "@tenstorrent/vesper/admonition";

export default function SecondaryAdmonition() {
  return (
    <Admonition variant="secondary">
      This admonition details some information.
    </Admonition>
  );
}
```

### Subtle

Passing `subtle` renders a variant with a more subdued appearance:

```tsx demo
import { Admonition } from "@tenstorrent/vesper/admonition";

export default function SubtleAdmonition() {
  return (
    <Admonition variant="warning" subtle>
      Subtle warning variant
    </Admonition>
  );
}
```

### Polymorphic CTA

You can use the `ctaAs` prop to specify what underlying element to render for the call-to-action. In this case, we are passing `ctaAs="a"` to render the call-to-action as an anchor link:

```tsx demo
import { Admonition } from "@tenstorrent/vesper/admonition";
import { Code } from "@tenstorrent/vesper/code";

export default function PolymorphicCtaAdmonition() {
  return (
    <Admonition
      variant="warning"
      ctaAs="a"
      cta={{ children: "Read docs", href: "#polymorphic-cta" }}
    >
      This option will be deprecated in <Code>v2.0</Code>.
    </Admonition>
  );
}
```