apps/design-system/content/docs/fragments/admonition.mdx
Admonition provides the standard product callout pattern for situations that require user attention.
<ComponentPreview name="admonition-demo" className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[70%]" peekCode wide />
Use Admonition instead of the low-level Alert primitive unless you specifically need custom composition. If in doubt, stick with Admonition.
Use Collapsible Alert when the callout needs to remain visible while optional detail can be expanded. Use Collapsible for generic disclosure behaviour that is not itself a callout.
Use title for the heading slot when the callout needs its own heading. title is optional: short callouts may use description without a title when nearby content already provides enough context.
Avoid title-only Admonitions in new code. A callout with title should also include description or children so it does not read like an incomplete heading.
import { Admonition } from 'ui-patterns/Admonition'
<Admonition
type="default"
title="Is it accessible?"
description="Yes. It adheres to the WAI-ARIA design pattern."
/>
Style the color of the button based upon the context of the Admonition, not its inherited type. For example, the below warning Admonition has an encouraged action, so its button has type="default". The destructive Admonition has a button that is destructive, so the button has type="danger".
<ComponentPreview name="admonition-button" className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[70%]" />
Only ever use the primary (green) button type on a default Admonition. Even then—given that Admonition is an isolated callout—the primary button type should rarely be used.
When a callout offers alternative ways to accomplish the same goal, use a split button instead of crowding the callout with multiple buttons. For related but distinct actions, use an overflow menu. See Table multiple actions.
<ComponentPreview name="admonition-button-split" className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[70%]" peekCode />
In responsive Admonitions, wrap the pair in flex w-full @lg:w-auto, give the primary flex-1 @lg:flex-none, and keep the chevron shrink-0.
<ComponentPreview name="admonition-demo" className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[70%]" />
Resize your browser to see the button(s) change layout based on the Admonition’s width.
<ComponentPreview name="admonition-responsive" className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[70%]" />
When layout="responsive", the Alert root gets @container so the Admonition is the container-query context. The Admonition stays vertical when it’s narrow and switches to horizontal when its own width reaches the @md container breakpoint, independent of page width.
<ComponentPreview name="admonition-warning" className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[70%]" />
There are several components that wrap the warning Admonition type with reusable text or functionality. These include:
AlertError for example rolls up consistent error handling and support contact methods.
Use description-only Admonitions for short callouts that sit near a heading or form label with enough context.
<ComponentPreview name="admonition-description-only" className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[70%]" />
Use success for positive, completed states where the user does not need to take corrective action.
<ComponentPreview name="admonition-success" className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[70%]" />
<ComponentPreview name="admonition-destructive" className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[70%]" />
Some Card or Dialog instances may need to include callout information in-between core content. Admonition can be used ‘full-bleed’ in these cases by removing borders and radii.
<ComponentPreview name="admonition-sandwiched" className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[70%]" />
Depending on the context, you may want to reset borders on the Admonition itself rather than the surrounding elements. The above Admonition is type "warning" with stark yellow borders which we want to emphasize.