Alert | iTwinUI

A small box to quickly grab the user's attention and communicate a brief message.

import * as React from 'react';
import { Alert } from '@itwin/itwinui-react';

export default () => {
  return (
    <Alert.Wrapper className='demo-alert-wrapper'>
      <Alert.Icon />
      <Alert.Message>
        This is an alert
        <Alert.Action onClick={() => console.log('Clicked more info!')}>
          Learn more
        </Alert.Action>
      </Alert.Message>
      <Alert.CloseButton onClick={() => console.log('CLOSED')} />
    </Alert.Wrapper>
  );
};

The alert message must be concise, it is recommended to have no more than 256 characters. If you need to provide additional information, consider using an optional hyperlink at the end of the alert message to explain more on a new page. You may also include an optional close icon (a close icon is mandatory for sticky alerts). Additionally it’s important to note that alerts are intended to inform users of information that is unrelated to their recent actions. Examples of alerts include announcing new product features or notifying the user of scheduled server maintenance and downtime. If you need to alert the user because of something they did, consider using a toast notification or an inline message.

Usage

Composition API

You can build Alerts with sub-components that are fully customizable.

<Alert.Wrapper type='positive'>
  <Alert.Icon />
  <Alert.Message>
    This is an alert
    <Alert.Action onClick={() => console.log('Clicked more info!')}>Learn more</Alert.Action>
  </Alert.Message>
  <Alert.CloseButton onClick={() => console.log('CLOSED')} />
</Alert.Wrapper>

Legacy API

Alternatively, you can use Alert directly, without any subcomponents. Although this pattern can suffice for simple cases, we strongly recommend using composition API for more flexibility. Some of the legacy props like clickableText/clickableTextProps may be removed in the future, as they encourage bad patterns.

The following code is equivalent to the composition example above:

<Alert
  type='positive'
  clickableText='Learn More'
  onClose={() => console.log('CLOSED')}
  clickableTextProps={{
    onClick={() => console.log('Clicked more info!')},
  }}
></Alert>

`<Alert.Action>`

The Alert.Action subcomponent can be used to provide additional information that may not fit the main message. Its behavior can be adjusted to navigate to another page, or perform an action on the same page (such as showing a dialog).

When href is passed, it behaves like a regular anchor link.
when onClick is passed, it behaves as a normal button.

Statuses

By default, Alerts will use type='informational'. The type prop can be changed to a specific status.

'positive': indication of a task that has been successfully completed.
'warning': requires attention but does not result in any immediate disruption.
'negative': signify system outages or failures.

import * as React from 'react';
import { Alert } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      {['positive', 'warning', 'negative'].map((type) => (
        <Alert.Wrapper key={type} type={type}>
          <Alert.Icon />
          <Alert.Message>
            This is a {type} alert
            <Alert.Action onClick={() => console.log('Clicked more info!')}>
              Learn more
            </Alert.Action>
          </Alert.Message>
          <Alert.CloseButton onClick={() => console.log('CLOSED')} />
        </Alert.Wrapper>
      ))}
    </div>
  );
};

Sticky Alert

Use the isSticky prop to fix an alert at the top of a user’s screen even if they scroll down the page. It’s important to note that sticky alerts must always be dismissible (using the close button). Additionally, the alert will appear above all other UI elements except for toast notifications and modals.

import * as React from 'react';
import { Alert, Text } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <Alert.Wrapper isSticky>
        <Alert.Icon />
        <Alert.Message>
          This is a sticky alert
          <Alert.Action onClick={() => console.log('Clicked more info!')}>
            Learn more
          </Alert.Action>
        </Alert.Message>
        <Alert.CloseButton onClick={() => console.log('CLOSED')} />
      </Alert.Wrapper>
      <Text className='demo-text'>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
        veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
        commodo consequat. Duis aute irure dolor in reprehenderit in voluptate
        velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
        occaecat cupidatat non proident, sunt in culpa qui officia deserunt
        mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur
        adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore
        magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
        laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
        in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
        pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa
        qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit
        amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
        labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
        exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
        Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
        dolore eu fugiat nulla pariatur.
      </Text>
    </div>
  );
};

It is up to the development team wether or not the sticky alert should push the rest of the content down or not.

Props

Prop	Description	Default
type	Type of the alert. "positive" \| "warning" \| "negative" \| "informational"	'informational'
isSticky	Stick the alert to the top. boolean	false
clickableText	@deprecated Use `Alert.Action` subcomponent. ReactNode
clickableTextProps	@deprecated Use `Alert.Action` subcomponent. Omit<DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, "ref">
onClose	@deprecated Use `Alert.CloseButton` subcomponent. () => void
as	"symbol" \| "object" \| "div" \| "a" \| "abbr" \| "address" \| "area" \| "article" \| "aside" \| "audio" \| "b" \| "base" \| "bdi" \| "bdo" \| "big" \| "blockquote" \| "body" \| "br" \| "button" \| "canvas" \| ... 158 more ... \| FunctionComponent<...>