Admonition

Used to communicate a state that affects a system, feature, or page.

• View on Github

• View Core API

• View on Figma

Import

import {
  Admonition,
  AdmonitionHeading,
  AdmonitionText,
} from '@pluralsight/react'

Anatomy

1. Container
2. Status icon
3. Heading
4. Text
5. Close button (optional)

Usage

Basic Admonition

function BasicExample() {
  return (
    <Admonition sentiment="info">
      <AdmonitionHeading>Note</AdmonitionHeading>
      <AdmonitionText>
        This is a basic admonition. It can be used to communicate a state that
        affects a system, feature, or page.
      </AdmonitionText>
    </Admonition>
  )
}

Admonition Status

function StatusesExample() {
  return (
    <div>
      <Admonition sentiment="info">
        <AdmonitionHeading>Note</AdmonitionHeading>
        <AdmonitionText>
          This is a info admonition. It can be used to communicate a state that
          affects a system, feature, or page.
        </AdmonitionText>
      </Admonition>

      <br />
      <Admonition sentiment="success">
        <AdmonitionHeading>Tip</AdmonitionHeading>
        <AdmonitionText>
          This is a success admonition. It can be used to communicate a tip or
          any other type of static information.
        </AdmonitionText>
      </Admonition>

      <br />
      <Admonition sentiment="warning">
        <AdmonitionHeading>Card Expiring Soon</AdmonitionHeading>
        <AdmonitionText>
          This is a warning admonition. It can be used to communicate a state
          that affects a system, feature, or page.
        </AdmonitionText>
      </Admonition>

      <br />
      <Admonition sentiment="danger">
        <AdmonitionHeading>Missing Payment</AdmonitionHeading>
        <AdmonitionText>
          This is a danger admonition. It can be used to communicate a state
          that affects a system, feature, or page.
        </AdmonitionText>
      </Admonition>
    </div>
  )
}

1. Info: Brings awareness to important information and sets expectations for the user.
2. Success: Provides the user with positive or helpful information for understanding a feature.
3. Warning: Helps users avoid error situations and should communicate important or time-sensitive states of the system.
4. Danger: Alerts of a problem that has already occurred that negatively affects the user experience.

Closable Admonition

To make an Admonition closable, pass a function to the onClose prop of the Admonition component. This function will be called when the user clicks the close button.

function ClosableAdmontionExample() {
  function handleClose(e) {
    console.log('close', e)
  }

  return (
    <Admonition sentiment="info" onClose={handleClose}>
      <AdmonitionHeading>Note</AdmonitionHeading>
      <AdmonitionText>
        All Pando React components are built using Typescript.
      </AdmonitionText>
    </Admonition>
  )
}

Customizing

There are 3 ways to customize the Admonition component.

1. Unused Classes

Each component layer of the Admontion has a unused class name that can be utilized in your local CSS to customize the Admonition at any level.

1. pando-admonition: The container of the Admonition.
2. pando-admonition-icon: The container of the status icon.
3. pando-admonition-text-container: The container of the text.
4. pando-admonition-heading: The heading element.
5. pando-admonition-text: The text element.
6. pando-icon-btn: The close button.

2. Passing a className prop

You can pass a className prop to the Admonition components to customize the Admonition at the container, heading, or text level. This is useful if your project uses CSS Modules or a CSS-in-JS library like Emotion.

import customStyles from './customStyles.module.css'

function CustomAdmonition(props) {
  return (
    <Admonition className={customStyles.container} {...props}>
      <AdmonitionHeading className={customStyles.heading}>
        Note
      </AdmonitionHeading>
      <AdmonitionText className={customStyles.text}>
        This is a basic admonition. It can be used to communicate a state that
        affects a system, feature, or page.
      </AdmonitionText>
    </Admonition>
  )
}

3. Ejected Admonition

For a low-level "ejected" approach, you can use the Headless-styles API to customize the Admonition however you prefer while keeping the accessibility behavior.

import {
  getAdmonitionProps,
  getAdmonitionHeadingProps,
  getAdmonitionTextProps,
  getAdmonitionIconProps,
  getAdmonitionCloseButtonProps,
  getIconProps,
  getIconButtonProps,
} from '@pluralsight/headless-styles'

To learn more about the Headless-styles API, check out the Headless-styles documentation.

Behavior

Placement

Do place at the top of the current content area, to capture the attention of users or be read as quickly as possible.

Don't place in the middle of a content area.

Do place at the beginning of a form.

Don't place in the middle or end of a form.

Status Icons

Do use the Icons we provide in the status section.

Don't use Icons outside of the examples we provide in the status section.

Close Button

Do include the Close button when the Admonition is communicating a real-time response or status to the user.

Don't use the Close button when the Admonition is static, warning, or informative messages.

API

Admonition: FC<AdmonitionProps>

interface AdmonitionProps extends HTMLAttributes<HTMLDivElement> {
  sentiment: 'info' | 'success' | 'warning' | 'danger'
  onClose?: MouseEventHandler<HTMLButtonElement>
}

Parameters

1. Any props that can be passed to a div element.
2. onClose: A function that will be called when the user clicks the close button. This is also used to display the close button.

AdmonitionHeading: FC<AdmonitionHeadingProps>

type AdmonitionHeadingProps = HTMLAttributes<HTMLParagraphElement>

Parameters

• Any props that can be passed to a p element.

AdmonitionText: FC<AdmonitionTextProps>

type AdmonitionTextProps = HTMLAttributes<HTMLParagraphElement>

Parameters

• Any props that can be passed to a p element.

Status Icons

const AdmonitionIconMap = {
  info: 'InfoCircleIcon',
  success: 'CheckCircleIcon',
  warning: 'WarningTriangleIcon',
  danger: 'DangerDiamondIcon',
}

Accessibility

The Pando Admonition is fully accessible and screen-readable through the following features:

1. Admonition is a div element with a role of "region".
2. Admonition Status Icon has an aria-hidden attribute of "true".
3. Admonition Close Button has an aria-label attribute of "Close admonition".
4. Admonition Button Icon has an aria-hidden attribute of "true" and a role of "img".