Instructure UI

https://instructure.design
Admin
Instructure UI is a comprehensive React component library with 100+ accessible components designed...
Tokens:7,585
Snippets:130
Trust Score:7.3
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Alert Package

Source: https://instructure.design/markdowns/Alert.md

Install the @instructure/ui-alerts package using npm. This is the first step before importing the component.

```shell
npm install @instructure/ui-alerts
```

--------------------------------

### Alert Usage Guidelines

Source: https://instructure.design/markdowns/Alert.md

Illustrates recommended and discouraged uses of the Alert component, including specific variants and accessibility attributes.

```html
---
type: embed
---
<Guidelines>
  <Figure recommendation="yes" title="Do">
    <Figure.Item>Use the Info alert to notify the user of more information</Figure.Item>
    <Figure.Item>Use the Error alert to notify user of an error</Figure.Item>
    <Figure.Item>Use the Warning alert to notify user of a warning</Figure.Item>
    <Figure.Item>Use the Success alert to notify user of a success event or action</Figure.Item>
    <Figure.Item>Use the `variantScreenReaderLabel` prop to indicate the alert variant to screen reader users</Figure.Item>
  </Figure>
  <Figure recommendation="no" title="Don't">
    <Figure.Item>Have alert messaging that is more than two lines long</Figure.Item>
    <Figure.Item>Overuse alerts on the same page</Figure.Item>
  </Figure>
</Guidelines>
```

```html
---
type: embed
---
<Guidelines>
  <Figure recommendation="a11y" title="Accessibility">
    <Figure.Item>If the alert requires user interaction to be dismissed, the alert should behave as a modal dialog. Focus should be set to the alert when it appears, remain in the alert until it is dismissed, and return to a logical place on the page when the alert is dismissed</Figure.Item>
    <Figure.Item>aria-live="polite" alerts will only be announced if the user is not currently doing anything. Polite should be used in most situations involving live regions that present new info to users</Figure.Item>
    <Figure.Item>aria-live="assertive" alerts will be announced to the user as soon as possible, but not necessarily immediately. Assertive should be used if there is information that a user must know about right away, for example, a warning message in a form that does validation on the fly</Figure.Item>
    <Figure.Item>The aria-atomic=BOOLEAN is used to set whether or not the screen reader should always present the live region as a whole, even if only part of the region changes. The possible settings are: false or true. The default setting is false.</Figure.Item>
  </Figure>
</Guidelines>
```

--------------------------------

### Alert Component Usage

Source: https://instructure.design/markdowns/Alert.md

This snippet demonstrates the basic structure and recommended usage of the Alert component with different variants.

```APIDOC
## Alert Component

### Description
Provides visual notifications to users for information, success, warning, or error states.

### Props

#### children
- **Type**: `ReactNode`
- **Required**: No
- **Default**: `null`
- **Description**: Content to be rendered within the Alert.

#### variant
- **Type**: `'info' | 'success' | 'warning' | 'error'`
- **Required**: No
- **Default**: `'info'`
- **Description**: Determines the color and icon of the alert.

#### variantScreenReaderLabel
- **Type**: `string`
- **Required**: No
- **Default**: `-`
- **Description**: Text used by screen readers to announce the alert variant. Example: "Information,"

#### liveRegion
- **Type**: `Element | null | (() => Element | null | undefined)`
- **Required**: No
- **Default**: `-`
- **Description**: A DOM element or function returning an element for screen reader alerts.

#### liveRegionPoliteness
- **Type**: `'polite' | 'assertive'`
- **Required**: No
- **Default**: `'assertive'`
- **Description**: Politeness level for screen reader alerts (`aria-live` attribute).

#### isLiveRegionAtomic
- **Type**: `boolean`
- **Required**: No
- **Default**: `false`
- **Description**: Controls whether the entire live region or only the changed part is read (`aria-atomic` attribute).

#### screenReaderOnly
- **Type**: `boolean`
- **Required**: No
- **Default**: `false`
- **Description**: If the alert should only be visible to screen readers.

#### timeout
- **Type**: `number`
- **Required**: No
- **Default**: `0`
- **Description**: Milliseconds until the Alert is dismissed automatically.

#### margin
- **Type**: `Spacing`
- **Required**: No
- **Default**: `'x-small 0'`
- **Description**: Spacing values for margins (e.g., `margin="small auto large"`).

#### renderCloseButtonLabel
- **Type**: `Renderable`
- **Required**: No
- **Default**: `-`
- **Description**: Label for the close button; can be a React component.

#### onDismiss
- **Type**: `() => void`
- **Required**: No
- **Default**: `-`
- **Description**: Callback function executed after the alert is closed.

#### transition
- **Type**: `'none' | 'fade'`
- **Required**: No
- **Default**: `'fade'`
- **Description**: Transition effect for the alert's appearance and disappearance.

#### open
- **Type**: `boolean`
- **Required**: No
- **Default**: `true`
- **Description**: Controls the visibility of the alert; setting to `false` triggers closing and unmounting.

#### hasShadow
- **Type**: `boolean`
- **Required**: No
- **Default**: `true`
- **Description**: Determines if the alert should have a shadow.

#### renderCustomIcon
- **Type**: `Renderable`
- **Required**: No
- **Default**: `-`
- **Description**: A custom icon or a function returning an icon to override the default variant icon.
```

--------------------------------

### Import Alert Component

Source: https://instructure.design/markdowns/Alert.md

Import the Alert component using ES Modules syntax. This allows for tree shaking, optimizing your bundle size.

```javascript
/*** ES Modules (with tree shaking) ***/
import { Alert } from '@instructure/ui-alerts'
```

--------------------------------

### Basic Alert Usage

Source: https://instructure.design/markdowns/Alert.md

Demonstrates the basic structure of an Alert component. Customize padding, border, and margin as needed.

```jsx
<View
  padding="small medium"
  borderWidth="small"
  borderRadius="small"
  margin="x-small 0"
>
  {lorem.paragraph()}
</View>
</View>
```

--------------------------------

### Dynamic Alerts with Live Region

Source: https://instructure.design/markdowns/Alert.md

Implements a feature to dynamically add alerts with varying politeness settings ('polite' or 'assertive') to a live region for screen reader announcements. Requires a static live region element.

```javascript
const Example = () => {
  const [alerts, setAlerts] = useState([])
  const [count, setcount] = useState(0)

  const variants = ['info', 'success', 'warning', 'error']

  const addAlert = () => {
    const variant = variants[count % variants.length]
    const politeness = Math.random() < 0.5 ? 'polite' : 'assertive'
    setAlerts([
      ...alerts,
      {
        key: count,
        variant,
        politeness
      }
    ])
    setcount(count + 1)
  }

  const closeAlert = (key) =>
    setAlerts(alerts.filter((alert) => alert.key !== key))

  return (
    <div>
      <Button onClick={addAlert}>Add Alert</Button>
      {alerts.map((alert) => {
        return (
          <View key={alert.key} display="block" margin="small 0">
            <Alert
              variant={alert.variant}
              renderCloseButtonLabel="Close"
              onDismiss={() => closeAlert(alert.key)}
              liveRegion={() => document.getElementById('flash-messages')}
              liveRegionPoliteness={alert.politeness}
              margin="small 0"
            >
              This is {alert.politeness === 'polite' ? 'a' : 'an'} 
              {alert.politeness} {alert.variant} alert
            </Alert>
          </View>
        )
      })}
    </div>
  )
}

render(<Example />)
```

--------------------------------

### Screen Reader Only Messages with Live Region

Source: https://instructure.design/markdowns/Alert.md

Demonstrates how to use an Alert component solely for screen reader announcements using `screenReaderOnly` and `liveRegion` properties. The message content is dynamic and changes on button click.

```javascript
const Example = () => {
  const [message, setMessage] = useState(null)
  const [count, setCount] = useState(1)

  const changeMessage = () => {
    setMessage(`this is message ${count}`)
    setCount(count + 1)
  }

  const clearMessage = () => {
    setMessage(null)
    setCount(count + 1)
  }

  return (
    <div>
      <Button onClick={changeMessage}>Change Message</Button>
      <Button onClick={clearMessage} margin="0 0 0 small">
        Clear Message
      </Button>
      <Alert
        liveRegion={() => document.getElementById('flash-messages')}
        isLiveRegionAtomic
        screenReaderOnly
      >
        {message}
      </Alert>
    </div>
  )
}

render(<Example />)
```

--------------------------------

### Inline Alert without Shadow

Source: https://instructure.design/markdowns/Alert.md

Illustrates how to render an alert inline without a shadow by setting the `hasShadow` prop to `false`. This is useful for alerts placed within other UI elements.

```javascript
<View as="div" background="primary" padding="large">
  <View
    as="div"
    background="primary"
    padding="small medium"
    borderWidth="small"
    borderRadius="small"
    margin="x-small 0"
  >
    {lorem.paragraph()}
  </View>
  <Alert
    variant="info"
    margin="x-small 0"
    renderCloseButtonLabel="Close"
    hasShadow={false}
  >
    This is an inline Alert, so it shouldn't have a shadow.
  </Alert>
  <View
    as="div"
    background="primary"

```

--------------------------------

### Alert Variants and Dismissibility

Source: https://instructure.design/markdowns/Alert.md

Demonstrates different alert variants (success, info, error, warning) with optional close buttons and margins. Some alerts include transitions, while others are static.

```javascript
<div>
  <Alert
    variant="success"
    renderCloseButtonLabel="Close"
    margin="small"
    transition="none"
    variantScreenReaderLabel="Success, "
  >
    Sample success alert text. I will close w/o a transition out if you close me
  </Alert>
  <Alert
    variant="info"
    renderCloseButtonLabel="Close"
    margin="small"
    variantScreenReaderLabel="Information, "
  >
    Sample info text. I will fade out if you close me.
  </Alert>
  <Alert
    variant="error"
    renderCloseButtonLabel="Close"
    margin="small"
    variantScreenReaderLabel="Error, "
  >
    Sample error text that continues for a while
    to demonstrate what happens when the content stretches over
    several lines. It really does take a lot of prose to get the
    text to wrap when you are on a high resolution screen.
  </Alert>
  <Alert
    variant="warning"
    margin="small"
    variantScreenReaderLabel="Warning, "
  >
    Sample warning text. This alert is not dismissible and cannot be closed.
  </Alert>
</div>
```

--------------------------------

### Auto-Dismissible Alert with Timeout

Source: https://instructure.design/markdowns/Alert.md

Shows an info alert that automatically dismisses after a specified time using the `timeout` prop.

```javascript
<Alert
  variant="info"
  margin="small"
  timeout={5000}
  variantScreenReaderLabel="Information, "
>
  Sample info text. I will fade out after 5 seconds
</Alert>
```
Tokens:
Raw