Building an Alert/Admonition Component

Build an Alert component for MDX — multiple variants (info, warning, error, success, tip), dismissible state, custom icons, and full accessibility.

Alerts (or callouts, or admonitions — pick your name) highlight the stuff readers shouldn't miss. Warnings, tips, errors, important notes. Plain text doesn't cut it for these — you need visual weight. Here's how to build a proper Alert component from scratch.

Why Alerts Matter in MDX

When you're writing docs or tutorials, some information is more important than the surrounding text. A well-styled alert says "hey, pay attention here" without you having to write that in words. Plus, they carry semantic meaning that screen readers can pick up on.

Component Source Code

Here's the full React implementation:

Example

// components/Alert.jsx import React, { useState } from 'react'; const alertStyles = { info: { bg: 'bg-blue-50 border-blue-400', text: 'text-blue-800', icon: 'ℹ️', darkBg: 'dark:bg-blue-900/30 dark:border-blue-500', darkText: 'dark:text-blue-200', }, warning: { bg: 'bg-yellow-50 border-yellow-400', text: 'text-yellow-800', icon: '⚠️', darkBg: 'dark:bg-yellow-900/30 dark:border-yellow-500', darkText: 'dark:text-yellow-200', }, error: { bg: 'bg-red-50 border-red-400', text: 'text-red-800', icon: '❌', darkBg: 'dark:bg-red-900/30 dark:border-red-500', darkText: 'dark:text-red-200', }, success: { bg: 'bg-green-50 border-green-400', text: 'text-green-800', icon: '✅', darkBg: 'dark:bg-green-900/30 dark:border-green-500', darkText: 'dark:text-green-200', }, tip: { bg: 'bg-purple-50 border-purple-400', text: 'text-purple-800', icon: '💡', darkBg: 'dark:bg-purple-900/30 dark:border-purple-500', darkText: 'dark:text-purple-200', }, }; export function Alert({ variant = 'info', title, children, dismissible = false, icon, className = '', }) { const [isVisible, setIsVisible] = useState(true); const styles = alertStyles[variant] || alertStyles.info; if (!isVisible) return null; return ( <div role="alert" aria-live="polite" className={` border-l-4 p-4 my-4 rounded-r-lg ${styles.bg} ${styles.darkBg} ${className} `} > <div className="flex items-start"> {/* Icon */} <span className="flex-shrink-0 mr-3 text-xl" aria-hidden="true"> {icon || styles.icon} </span> {/* Content */} <div className="flex-1"> {title && ( <h4 className={`font-semibold mb-1 ${styles.text} ${styles.darkText}`}> {title} </h4> )} <div className={`text-sm ${styles.text} ${styles.darkText}`}> {children} </div> </div> {/* Dismiss Button */} {dismissible && ( <button onClick={() => setIsVisible(false)} className={`ml-3 flex-shrink-0 ${styles.text} hover:opacity-70 transition-opacity`} aria-label="Dismiss alert" > <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 20 20"> <path fillRule="evenodd" d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z" clipRule="evenodd" /> </svg> </button> )} </div> </div> ); }

Usage in MDX

Import the component and drop it into your content:

mdx example

import { Alert } from '../components/Alert';

# My Documentation Page

Here's some regular content in your MDX file.

<Alert variant="info" title="Note">
  This is an informational alert that provides additional context
  to the reader without interrupting the flow of content.
</Alert>

<Alert variant="warning" title="Caution">
  Be careful when modifying configuration files. Always create
  a backup before making changes.
</Alert>

<Alert variant="error" title="Breaking Change">
  This API endpoint was removed in v3.0. Please migrate to the
  new `/api/v3/users` endpoint immediately.
</Alert>

<Alert variant="success" title="Complete">
  Your deployment was successful! The changes are now live
  in production.
</Alert>

<Alert variant="tip" title="Pro Tip">
  You can combine multiple MDX components together for richer
  documentation experiences.
</Alert>

Dismissible Alert Example

Let users close the alert once they've read it:

mdx example

<Alert variant="info" title="First Time Here?" dismissible>
  Welcome to our documentation! Check out the getting started
  guide for a quick overview of key concepts.
</Alert>

Custom Icon Example

Override the default emoji with whatever you want:

mdx example

<Alert variant="info" title="Rocket Launch" icon="🚀">
  Your application has been deployed to production successfully.
</Alert>

Alerts with Rich MDX Content

You can put markdown, links, code, and lists inside alerts:

Example

<Alert variant="tip" title="Code Inside Alerts"> You can include inline code like `npm install` or even links to [external resources](https://example.com) inside alerts. - Bullet points work too - Making alerts very flexible </Alert>

Props API Documentation

Prop	Type	Default	Description
`variant`	`'info' \	'warning' \	'error' \	'success' \	'tip'`	`'info'`	Visual style variant of the alert
`title`	`string`	`undefined`	Optional title displayed in bold above content
`children`	`ReactNode`	required	The alert content (supports MDX/JSX)
`dismissible`	`boolean`	`false`	Whether the alert can be dismissed by the user
`icon`	`string \	ReactNode`	variant default	Custom icon to override the default variant icon
`className`	`string`	`''`	Additional CSS classes for custom styling

Styling with CSS Modules (Alternative to Tailwind)

Prefer plain CSS? Here's the equivalent:

css example

/* Alert.module.css */
.alert {
  border-left: 4px solid;
  padding: 1rem;
  margin: 1rem 0;
  border-radius: 0 0.5rem 0.5rem 0;
  display: flex;
  align-items: flex-start;
}

.alert-info {
  background-color: #eff6ff;
  border-color: #60a5fa;
  color: #1e40af;
}

.alert-warning {
  background-color: #fffbeb;
  border-color: #fbbf24;
  color: #92400e;
}

.alert-error {
  background-color: #fef2f2;
  border-color: #f87171;
  color: #991b1b;
}

.alert-success {
  background-color: #f0fdf4;
  border-color: #4ade80;
  color: #166534;
}

.alert-tip {
  background-color: #faf5ff;
  border-color: #c084fc;
  color: #6b21a8;
}

.alert-icon {
  flex-shrink: 0;
  margin-right: 0.75rem;
  font-size: 1.25rem;
}

.alert-content {
  flex: 1;
}

.alert-title {
  font-weight: 600;
  margin-bottom: 0.25rem;
}

.alert-dismiss {
  margin-left: 0.75rem;
  background: none;
  border: none;
  cursor: pointer;
  opacity: 0.7;
  transition: opacity 0.2s;
}

.alert-dismiss:hover {
  opacity: 1;
}

Icon Integration with React Icons

For production, you'll probably want real icons instead of emoji:

Example

import { FiInfo, FiAlertTriangle, FiXCircle, FiCheckCircle, FiZap } from 'react-icons/fi'; const iconMap = { info: <FiInfo className="w-5 h-5" />, warning: <FiAlertTriangle className="w-5 h-5" />, error: <FiXCircle className="w-5 h-5" />, success: <FiCheckCircle className="w-5 h-5" />, tip: <FiZap className="w-5 h-5" />, }; // Use inside the component: <span className="flex-shrink-0 mr-3" aria-hidden="true"> {icon || iconMap[variant]} </span>

Accessibility Notes

Here's what makes this accessible and why each piece matters:

role="alert" — Tells screen readers this is an alert region. Content gets announced immediately when it appears.

aria-live="polite" — For non-critical alerts, screen readers wait for a pause before announcing. Use aria-live="assertive" for errors that need immediate attention.

aria-hidden="true" on icons — The icons are decorative. Screen readers skip them since the meaning comes from the text.

aria-label="Dismiss alert" on close button — The button only has an SVG icon, so it needs a text label for screen readers.

Keyboard support — The dismiss button is a native <button>, so it's focusable and works with Enter/Space automatically.

Color is not the only indicator — Icons and text labels back up the color coding. Colorblind users can still tell alert types apart.

Advanced: Auto-Dismissing Alert

Want an alert that disappears after a few seconds?

Example

export function AutoDismissAlert({ duration = 5000, ...props }) { const [visible, setVisible] = useState(true); useEffect(() => { const timer = setTimeout(() => setVisible(false), duration); return () => clearTimeout(timer); }, [duration]); if (!visible) return null; return <Alert {...props} />; }

MDXProvider Registration

Make alerts available globally so you don't need imports in every file:

Example

// mdx-components.js or your provider setup import { Alert } from './components/Alert'; export const mdxComponents = { Alert, // Shorthand aliases for convenience in MDX Info: (props) => <Alert variant="info" {...props} />, Warning: (props) => <Alert variant="warning" {...props} />, Error: (props) => <Alert variant="error" {...props} />, Success: (props) => <Alert variant="success" {...props} />, Tip: (props) => <Alert variant="tip" {...props} />, };

Now authors can use shorthand without any imports:

mdx example

<Tip title="Quick Shorthand">
  When registered globally, you don't need imports!
</Tip>

Summary

The Alert component covers the key patterns you'll reuse everywhere: variant-based styling, composable children, accessibility-first markup, and optional interactivity (dismissible state). Once you have this, you can build callouts, banners, toasts — same core pattern, different skin.

Why Alerts Matter in MDX

Component Source Code

Here's the full React implementation:

Example

Usage in MDX

Import the component and drop it into your content:

mdx example

import { Alert } from '../components/Alert';

# My Documentation Page

Here's some regular content in your MDX file.

<Alert variant="info" title="Note">
  This is an informational alert that provides additional context
  to the reader without interrupting the flow of content.
</Alert>

<Alert variant="warning" title="Caution">
  Be careful when modifying configuration files. Always create
  a backup before making changes.
</Alert>

<Alert variant="error" title="Breaking Change">
  This API endpoint was removed in v3.0. Please migrate to the
  new `/api/v3/users` endpoint immediately.
</Alert>

<Alert variant="success" title="Complete">
  Your deployment was successful! The changes are now live
  in production.
</Alert>

<Alert variant="tip" title="Pro Tip">
  You can combine multiple MDX components together for richer
  documentation experiences.
</Alert>

Dismissible Alert Example

Let users close the alert once they've read it:

mdx example

<Alert variant="info" title="First Time Here?" dismissible>
  Welcome to our documentation! Check out the getting started
  guide for a quick overview of key concepts.
</Alert>

Custom Icon Example

Override the default emoji with whatever you want:

mdx example

<Alert variant="info" title="Rocket Launch" icon="🚀">
  Your application has been deployed to production successfully.
</Alert>

Alerts with Rich MDX Content

You can put markdown, links, code, and lists inside alerts:

Example

Props API Documentation

Prop	Type	Default	Description
`variant`	`'info' \	'warning' \	'error' \	'success' \	'tip'`	`'info'`	Visual style variant of the alert
`title`	`string`	`undefined`	Optional title displayed in bold above content
`children`	`ReactNode`	required	The alert content (supports MDX/JSX)
`dismissible`	`boolean`	`false`	Whether the alert can be dismissed by the user
`icon`	`string \	ReactNode`	variant default	Custom icon to override the default variant icon
`className`	`string`	`''`	Additional CSS classes for custom styling

Styling with CSS Modules (Alternative to Tailwind)

Prefer plain CSS? Here's the equivalent:

css example

/* Alert.module.css */
.alert {
  border-left: 4px solid;
  padding: 1rem;
  margin: 1rem 0;
  border-radius: 0 0.5rem 0.5rem 0;
  display: flex;
  align-items: flex-start;
}

.alert-info {
  background-color: #eff6ff;
  border-color: #60a5fa;
  color: #1e40af;
}

.alert-warning {
  background-color: #fffbeb;
  border-color: #fbbf24;
  color: #92400e;
}

.alert-error {
  background-color: #fef2f2;
  border-color: #f87171;
  color: #991b1b;
}

.alert-success {
  background-color: #f0fdf4;
  border-color: #4ade80;
  color: #166534;
}

.alert-tip {
  background-color: #faf5ff;
  border-color: #c084fc;
  color: #6b21a8;
}

.alert-icon {
  flex-shrink: 0;
  margin-right: 0.75rem;
  font-size: 1.25rem;
}

.alert-content {
  flex: 1;
}

.alert-title {
  font-weight: 600;
  margin-bottom: 0.25rem;
}

.alert-dismiss {
  margin-left: 0.75rem;
  background: none;
  border: none;
  cursor: pointer;
  opacity: 0.7;
  transition: opacity 0.2s;
}

.alert-dismiss:hover {
  opacity: 1;
}

Icon Integration with React Icons

For production, you'll probably want real icons instead of emoji:

Example

Accessibility Notes

Here's what makes this accessible and why each piece matters:

role="alert" — Tells screen readers this is an alert region. Content gets announced immediately when it appears.

aria-live="polite" — For non-critical alerts, screen readers wait for a pause before announcing. Use aria-live="assertive" for errors that need immediate attention.

aria-hidden="true" on icons — The icons are decorative. Screen readers skip them since the meaning comes from the text.

aria-label="Dismiss alert" on close button — The button only has an SVG icon, so it needs a text label for screen readers.

Keyboard support — The dismiss button is a native <button>, so it's focusable and works with Enter/Space automatically.

Color is not the only indicator — Icons and text labels back up the color coding. Colorblind users can still tell alert types apart.

Advanced: Auto-Dismissing Alert

Want an alert that disappears after a few seconds?

Example

MDXProvider Registration

Make alerts available globally so you don't need imports in every file:

Example

Now authors can use shorthand without any imports:

mdx example

<Tip title="Quick Shorthand">
  When registered globally, you don't need imports!
</Tip>

Building an Alert/Admonition Component

Why Alerts Matter in MDX

Component Source Code

Usage in MDX

Dismissible Alert Example

Custom Icon Example

Alerts with Rich MDX Content

Props API Documentation

Styling with CSS Modules (Alternative to Tailwind)

Icon Integration with React Icons

Accessibility Notes

Advanced: Auto-Dismissing Alert

MDXProvider Registration

Summary

Continue learning this concept

Building an Alert/Admonition Component

Why Alerts Matter in MDX

Component Source Code

Usage in MDX

Dismissible Alert Example

Custom Icon Example

Alerts with Rich MDX Content

Props API Documentation

Styling with CSS Modules (Alternative to Tailwind)

Icon Integration with React Icons

Accessibility Notes

Advanced: Auto-Dismissing Alert

MDXProvider Registration

Summary

Continue learning this concept