import { Indicator } from '@uhg-abyss/web/ui/Indicator';Usage
To apply, wrap the Indicator component around an existing element. By default the Indicator will be positioned in the top-right corner of the child element. Please note that there are accessibility concerns when utilizing this component and further information can be found on the Accessibility tab of this page as well as below in the Indicator type / Focusable element sections. For further details on implementation, please see the various sections below.
<Indicator label={5}> <Badge> Indicator Sandbox </Badge></Indicator>Offset
Use the offset prop to change the position of the Indicator. It is useful when the Indicator component is used with children that have a border radius.
Label
Use the label prop to pass in the content that will be displayed within the Indicator. The value can be either a number or string.
If no label is provided, then the Indicator will be styled as a smaller circle.
Overflow count
Use the overflowCount prop to show the Indicator label content with a + symbol when the Indicator label value has surpassed the overflowCount value. Default is 99.
Show zero
Use the showZero={false} prop to hide the Indicator when the label value is 0. The default is set to true.
Color
Use the color prop to change the color of the Indicator.
Indicator type
Use the indicatorType prop to pass additional description text that will be appended to the label text and read by a screen reader to provide the user context of the Indicator's role. This text will always remain hidden from display and is exclusively used for accessibility purposes. The default value is Notifications.
Focusable element
Indicator is not focusable. If a focusable element is wrapped with the Indicator you will need to pass an aria-label to the focusable element. The aria-label text should include the Indicator label content and information about the Indicator's role. For example aria-label="Indicator with [label] notifications". Please see the example below for further details on implementation.
Indicator Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
children | React.ReactNode | - | - | The contents of the indicator component |
className | string | - | - | CSS class name to apply to each element within the component |
color | string | - | - | The color of the indicator |
css | Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>> | - | - | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation |
data-testid | string | - | - | Suffix used to create a unique ID used for automated testing |
disableDefaultProviderProps | boolean | false | - | If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored. |
indicatorType | string | 'Notifications' | - | The type of indicator for accessibility text |
label | string | number | - | - | The label to display inside the indicator |
noAnnounce | boolean | false | - | Prevents announcement for screen readers, to be used when wrapped components handle it instead |
offset | number | 0 | - | The offset for the indicator position |
overflowCount | number | 99 | - | The maximum value to display before showing overflow (e.g. 99+) |
position | IndicatorPosition | 'top-end' | - | The position of the indicator |
showZero | boolean | true | - | Whether to show the indicator when the label is 0 |
Indicator Classes
| Class Name | Description |
|---|---|
| .abyss-indicator-root | Indicator root element |
| .abyss-indicator-container | Indicator container element |
| .abyss-indicator-label | Indicator label element |
Focusable element
Indicator is not focusable. If a focusable element is wrapped with the Indicator you will need to pass an aria-label to the focusable element. The aria-label text should include the Indicator label content and information about the Indicator's role. For example aria-label="Indicator with [label] notifications". Please see the example below for further details on implementation.
To avoid duplicate announcements, you can also pass the noAnnounce prop to the Indicator component. This will allow the wrapped focusable element to handle off-screen announcements instead.
Dynamic label content
After initial load, anytime the Indicator label content is updated, a role="alert" attribute will be applied to ensure that screen readers will announce the updated content. Please see the example above for a demonstration of this in action.
Character limit
While there is no explicit limit on the number of text characters that can be used in the Indicator, be mindful that the wider the Indicator, the greater the risk of blocking surrounding information from view.
Offset
Like the character limit, be cognizant of the Indicator positioning in relation to the element it is paired with, particularly with icons that are sized dynamically. Avoid fixed values or large offsets that could potentially overlap or cover the paired icon or surrounding content.
Color contrast
As with all components, the color contrast of the text within the Indicator to the background color must be at least 4.5:1. Additionally, the background circle shape must have a minimum of 3:1 color contrast with the icon/element it's attached to as well as the surrounding background. Please find link for color contrast guide Color Contrast.
Additional examples
Component Tokens
Note: Click on the token row to copy the token to your clipboard.
Indicator Tokens
| Token Name | Value | |
|---|---|---|
| indicator.color.surface.container | #990000 | |
| indicator.color.text.label | #FFFFFF | |
| indicator.color.border.container | #FFFFFF | |
| indicator.border-radius.all.container | 500px | |
| indicator.border-width.all.container.default | 1px | |
| indicator.border-width.all.container.thick | 2px | |
| indicator.spacing.padding.horizontal.label | 4px |