Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adds content to alert group react examples. #7763

Merged
merged 6 commits into from
Sep 7, 2022
Merged
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -6,37 +6,73 @@ propComponents: ['Alert', 'AlertGroup', 'AlertActionCloseButton', 'AlertActionLi
---

## Examples
### Static alert group
These alerts appear on page load and are discoverable from within the normal page content flow, and will not be announced individually/explicitly to assistive technology.

### Variants

Alert groups can be the following variants:
| Variant | Description |
edonehoo marked this conversation as resolved.
Show resolved Hide resolved
| --- | --- |
| Static inline | Static inline alert groups contain alerts that appear when the page loads, and are seen within the normal page content flow. Static alert groups should not contain alerts that will dynamically appear or update. |
| Toast (dynamic) | Toast alert groups position alerts on top of other content at the top right of the page. |
| Dynamic | Dynamic alert groups appear in line with the page's content flow, often in response to a user action.|
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| Toast (dynamic) | Toast alert groups position alerts on top of other content at the top right of the page. |
| Dynamic | Dynamic alert groups appear in line with the page's content flow, often in response to a user action.|
| Toast (dynamic) | Toast alert groups contain alerts that often appear in response to an asynchronous event or user action, and position alerts on top of other content at the top right of the page. |
| Dynamic | Dynamic alert groups contain alerts that often appear in response to a user action, and position alert inline with the page's content flow. |

Or something along those lines. Based on @mcarrano comment above about that async example, adding some verbiage about that here may not be bad. Part of the intent is also to help differentiate when one would want to use a toast alert group since it and the normal dynamic group are fairly similar.


Dynamic alerts are generated after the page initially loads. Additional measures are required to ensure these alerts are accessible to screen readers.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bit of a tweak here, to combine some verbiage you had elsewhere and bring it up here to a less specific section:

Suggested change
Dynamic alerts are generated after the page initially loads. Additional measures are required to ensure these alerts are accessible to screen readers.
Dynamic alerts that are generated after the page initially loads must be appended to either a "toast" or "dynamic" `AlertGroup` and the group must have the `isLiveRegion` prop passed in.
By default, only new alerts appended to a toast or dynamic group will be announced by assistive technologies when the `isLiveRegion` prop is passed into the group. For information about customizing this announcement, read the [aria-atomic and aria-relevant](/components/alert-group/accessibility#aria-atomic-and-aria-relevant) section of the alert group accessibility documentation.

Or something along those lines. Basically the goals I had with this tweak is to make it clear you must pass in isLiveRegion to the alert group when alerts will be dynamic, and to link to the a11y docs for aria-atomic/aria-relevant (which was originally mentioned further down).


### Static inline alert group

Alert groups may combine multiple [alert variants](components/alert/), as shown in the following static alert group example.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

```ts file="./AlertGroupStatic.tsx"
```

### Toast alert group
Alerts asynchronously appended into dynamic AlertGroups with `isLiveRegion` will be announced to assistive technology at the moment the change happens, following the strategy used for aria-atomic, which defaults to false. This means only changes of type "addition" will be announced.

Alerts that are asynchronously appended into dynamic `AlertGroups` with `isLiveRegion` will be announced to assistive technology at the moment the change happens, following the strategy used for `aria-atomic`, which defaults to `false`. This means only changes of type `addition` will be announced.

The following example uses `isLiveRegion` to add toast alerts to a group after a button click, but does not set `aria-atomic` to `addition`.
Copy link
Contributor

@thatblindgeye thatblindgeye Aug 22, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just some minor tweaks here, based on the suggestion I made a bit further down at #7763 (comment)

Suggested change
Alerts that are asynchronously appended into dynamic `AlertGroups` with `isLiveRegion` will be announced to assistive technology at the moment the change happens, following the strategy used for `aria-atomic`, which defaults to `false`. This means only changes of type `addition` will be announced.
The following example uses `isLiveRegion` to add toast alerts to a group after a button click, but does not set `aria-atomic` to `addition`.
An `AlertGroup` can be turned into a toast group by passing in the `isToast` and `isLiveRegion` properties. Alerts that are asynchronously appended into a toast `AlertGroup` will be announced to assistive technology at the moment the change happens.
The following example adds alerts to a toast group after a button is clicked.


```ts file="./AlertGroupToast.tsx"
```

### Toast alert group with overflow capture
After a specified number of alerts displayed is reached, we will see an overflow message instead of new alerts. Alerts asynchronously appended into dynamic AlertGroups with `isLiveRegion` will be announced to assistive technology at the moment the change happens. When the overflow message appears or is updated in AlertGroups with `isLiveRegion`, the `View 1 more alert` text will be read, but the alert message will not be read. screen reader user or keyboard user will need a way to navigate to and reveal the hidden alerts before they disappear. Alternatively, there should be a place that notifications or alerts are collected to be viewed or read later. In this example we are showing a max of 4 alerts.

After a specified number of alerts displayed is reached, users will see an overflow message instead of new alerts. In the following example, an overflow message will appear when more than four alerts are queued.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

When the overflow message appears in an `AlertGroup` with `isLiveRegion`, the "view 1 more alert" text label will be read, but the alert message will not be read.

Screen reader and keyboard users will need a way to navigate to and reveal the hidden alerts before they disappear. Alternatively, there should be a place where notifications or alerts are collected to be viewed or read later.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

```ts file="AlertGroupToastOverflowCapture.tsx" isBeta
```
### Dynamic alert groups

Dynamic alerts are generated after the page initially loads and appear within the normal page content flow. Additional measures are required to ensure these alerts are accessible to screen readers.

Click the buttons in the example below to add different alert variants to a group.

### Singular dynamic alert group
This alert will appear in the page, most likely in response to a user action.
```ts file="./AlertGroupSingularDynamic.tsx"
```

### Singular dynamic alert group with overflow message
This alert will appear in the page, most likely in response to a user action. In this example we are showing a max of 4 alerts.
### Dynamic alert group with overflow message

In the following example, there can be a max of four alerts shown at once, based on the value of `maxDisplayed`. If there are more than the set maximum of alerts on a page, an overflow message will appear, which users can click on to see the full list of alerts. You may adjust the maximum number of allowed alerts as needed.
edonehoo marked this conversation as resolved.
Show resolved Hide resolved


```ts file="AlertGroupSingularDynamicOverflow.tsx" isBeta
```

### Multiple dynamic alert group
These alerts will appear in the page, most likely in response to a user action.
### Multiple dynamic alert groups

You may generate multiple alerts within a group at once. Click the "add alert collection" button in the example below to add three toast alerts to a group at once.

```ts file="./AlertGroupMultipleDynamic.tsx"
```

### Async alert group
This shows how an alert could be triggered by an asynchronous event in the application. Note how you can customize how the alert will be announced to assistive technology. See the alert group accessibility tab for more information.
### Asynchronous alert groups
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

This example shows how alerts can be triggered by an asynchronous event in the application. You can customize how the alert will be announced to assistive technology by adjusting the value of the `aria-live` property. Click the "start async" alert button below and then click the buttons in the above examples to demonstrate how this may work in practice. Click the "stop async alerts" button to halt this behavior.

See the [alert group accessibility tab](/components/alert-group/accessibility) for more information on the customization options.

```ts file="./AlertGroupAsync.tsx"
```