---
title: Admonition
description: Semantic callout blocks for highlighting side content, alerts, and status messages
status: beta
---

<ComponentPreview name="admonition-demo" dependencies={["lucide-react"]} />

## Installation

<Installation name="admonition" dependencies={["lucide-react"]} />

## Usage

The Admonition component wraps content with semantic coloring and iconography. It is designed to fit seamlessly into prose or application UIs.

```tsx
import { Admonition } from "@/components/ui/admonition"

export default function Example() {
  return (
    <Admonition type="warning" title="Production Database">
      You are currently editing the production database. Changes here are
      irreversible.
    </Admonition>
  )
}
```

## Examples

### Variants

The component comes with 7 semantic types, each with its own color scheme and icon.

<ComponentPreview
  name="admonition-demo-interactive"
  dependencies={["lucide-react"]}
/>

### Dismissible State

You can allow users to permanently dismiss an admonition using the `dismissible` prop.

**Crucially**, you must provide a unique `dismissKey`. The component uses this key to persist the dismissed state in `localStorage`. If the user refreshes the page, the admonition will remain hidden.

<ComponentPreview name="admonition-dismissible-demo" />

### Collapsible

For long-form content, use the `collapsible` prop. Unlike standard accordions, this component uses CSS line-clamping to show a preview of the content when collapsed, rather than hiding it completely.

<ComponentPreview name="admonition-collapsible-demo" />

## Sizing

The component supports three distinct sizes. `default` is optimized for standard prose, while sm is excellent for dense dashboards or sidebar alerts.

<ComponentPreview name="admonition-small-demo" />

### Custom Icon

You can override the semantic icon by passing a generic SVG component (like Lucide React icons) to the `icon` prop.

<ComponentPreview name="admonition-custom-icon-demo" />

### With Actions

You can add interactive buttons to the bottom of the admonition using the `actions` prop. These buttons automatically inherit the color theme of the admonition type.

<ComponentPreview name="admonition-actions-demo" />

## Notes

### Text Alignment & CSS

The component uses `[text-box-trim:trim-start]` on the title and content. This is a modern CSS technique that removes the leading whitespace from the font's bounding box, ensuring the text cap-height aligns perfectly with the icon regardless of the font family used in your project.

### Hydration & Persistence

When using `dismissible`, the component checks `localStorage` inside a `useEffect` hook. This ensures the component is compatible with Server Side Rendering (SSR) and won't cause hydration mismatch errors, though it may result in a strictly visual layout shift if the component mounts and then immediately hides itself.

## API Reference

| Prop               | Type                                                                           | Default     | Description                                                       |
| ------------------ | ------------------------------------------------------------------------------ | ----------- | ----------------------------------------------------------------- |
| `type`             | `"note" \| "tip" \| "info" \| "warning" \| "danger" \| "success" \| "caution"` | `"note"`    | The semantic variant determining color and default icon.          |
| `title`            | `string`                                                                       | —           | Optional header text.                                             |
| `children`         | `ReactNode`                                                                    | —           | The content body.                                                 |
| `icon`             | `ComponentType`                                                                | —           | Override the default icon.                                        |
| `dismissible`      | `boolean`                                                                      | `false`     | Renders a close button.                                           |
| `dismissKey`       | `string`                                                                       | —           | Required if `dismissible` is true. Unique key for `localStorage`. |
| `collapsible`      | `boolean`                                                                      | `false`     | Renders a chevron to toggle content visibility.                   |
| `defaultCollapsed` | `boolean`                                                                      | `false`     | Sets the initial state if `collapsible` is true.                  |
| `size`             | `"sm" \| "default" \| "lg"`                                                    | `"default"` | Controls padding and font sizing.                                 |
| `className`        | `string`                                                                       | —           | Additional CSS classes for the container.                         |