We are following standard package procedures. You can install the component using NPM or Yarn.
npm install @tournant/notification --save
If you use Yarn:
yarn add @tournant/notification
Once the component is installed you need to import it wherever you want to use it.
Don’t forget to add it to the registered components (been there, done that):
components:TournantNotification// ... all the other amazing components
The default usage of this component is the implementation of the
status role. This role sets
polite, meaning that the text content of the component will be read after the screenreader has finished its current output.
If you need to announce something important, change the prop
type to be
assertive. This will render the component with a role of
alert and interrupt a screen reader in its current output.
Usage as a status message
A status message is a message that will be announced after the current output. It is useful if, say, a new page has been loaded. This is the default behaviour.
<!-- Input !--><!-- Output -->Page 4 has been loaded>
Usage as an alert message
An alert will be announced immdiately. It is useful if, say, a critical error has occured.
<!-- Input !--><!-- Output -->There has been an error parsing your data>
The following props can be used to control the component:
message: Required. A string that should be added to page and read out by screen readers.
info. A state level, with which you can control visual representation. See section #css below.
polite. Controls the announcement by a screen reader. Must be either
5. The time which should pass before the message is hidden.
Alerts are only status messages. As such, they do not require user interaction. The spec is pretty clear:
Neither authors nor user agents are required to set or manage focus to them in order for them to be processed. Since alerts are not required to receive focus, content authors SHOULD NOT require users to close an alert.
That’s why it is important to clear messages after a while. The while depends on the length of your messages. We use a default value of five seconds. But you are free to change to this with the
Note: It is named hideAfterSeconds. We multiply the value by 1,000 in the component. Do not pass miliseconds as a value.
Once the timeout elapses, the component sets
display: none. We do this to make it easier to comply with the ARIA requirements. You should, nonetheless, take care of discarding old messages in your app yourself.
TalkBack Usage Notes
From our testing it seems as if TalkBack on Android reads alert content twice.
The component exposes the
t-ui-alert class by default. Additionally it will set the current state prepended by «is» as its class. Some examples:
<!-- Input !--><!-- Output !-->404 Not Found<!-- Input !--><!-- Output !-->200 OK
States can be whatever you want:
<!-- Input !--><!-- Output !-->418 I’m a Teapot
These can act as a helper to style the component matching the state.
If the timeout elapsed and the message has not been removed from the outside,
aria-hidden will be set to true. To keep the UI in sync,
display: none is added to the root element.
The component will emit the event
messageTimeout as soon as the timeout elapses. You can use this event to run a clean-up task in your app.
Bugs & Enhancements
If you found a bug, please create a bug ticket.
For enhancements please refer to the contributing guidelines.