Banner
<ahi-banner> | AhiBanner
Banners inform users about important changes or persistent conditions. Use this component if you need to communicate to users in a prominent way. Banners are placed at the top of the page or section they apply to, and below the page or section header.
The default banner is used to convey general information or actions that aren’t critical. Default banners contain lower priority information and should always be closable.
<ahi-banner open closable>
We are working on APIs that will allow developers to tap into Azalea Health's platform and are opening a selection of
these resources to a small number of private beta partners. If you are interested in becoming a beta partner, or want
to learn more about how you can integrate your product with Azalea Health, please contact us.
</ahi-banner>
Banners will not be visible if the open attribute is not present.
Examples
Informational
Use to update users about a change or give them advice.
<ahi-banner variant="info" title="Pro Tip!" open closable>
Use the datepicker to select a range, then use the buttons to set the granularity.
</ahi-banner>
Inside an info banner, interactive content moves one state along the interactive colors: at rest it takes
the usual hover color, and on hover the usual pressed color. The standard interactive blue falls just short
of 4.5:1 on the info tint in the light theme, and this lifts it clear. Nothing needs to be set: an
ahi-link, an <ahi-button plain> and any other control in the banner that uses these colors, such
as a checked checkbox or a toggle, pick it up. Its contrast only goes up, against the tint and against its
own checkmark or thumb.
<ahi-banner variant="info" open>
Your visit summary is ready. <a class="ahi-link" href="#">Review it before your next appointment</a>.
</ahi-banner>
Success
Default to using toasts for success messages, unless the feedback is delayed, persistent, or has a call to action. Include next steps if applicable.
<ahi-banner variant="success" title="Your report is ready to print." open closable>
<ahi-button outline>Print report</ahi-button>
</ahi-banner>
Warning
Use to display information that needs attention or that users need to take action on.
<ahi-banner variant="warning" title="Before you can save this patient, this change needs to be made:" open>
The name of the patient has characters that aren't allowed. The name can not include spaces or hyphens.
<br />
<ahi-button outline>Edit name</ahi-button>
</ahi-banner>
Critical
Use to communicate problems that have to be resolved immediately for users to complete a task.
For your protection, you need to change your password.
<ahi-banner variant="critical" title="Suspicious account activity detected" open>
<p>For your protection, you need to change your password.</p>
<div class="ahi-row ahi-gap-0">
<ahi-button outline>Change password</ahi-button>
<ahi-button plain>Review account activity</ahi-button>
</div>
</ahi-banner>
Duration
Set the duration attribute to automatically hide a banner after a period of time. This is
useful for banners that don’t require acknowledgement.
<div class="banner-duration">
<ahi-button>Show Banner</ahi-button>
<ahi-banner duration="3000" closable>
This banner will automatically hide itself after three seconds, unless you interact with it.
</ahi-banner>
</div>
<script>
const container = document.querySelector('.banner-duration');
const button = container.querySelector('ahi-button');
const banner = container.querySelector('ahi-banner');
button.addEventListener('click', () => banner.show());
</script>
<style>
.banner-duration ahi-button {
margin: var(--ahi-space-4) 0;
}
</style>
Countdown
Set the countdown attribute to display a loading bar that indicates the banner remaining time.
This is useful for alerts with relatively long duration.
<div class="banner-countdown">
<ahi-button>Show Banner</ahi-button>
<ahi-banner duration="10000" countdown closable>
The banner will close after a pretty long duration.
</ahi-banner>
</div>
<script>
const container = document.querySelector('.banner-countdown');
const button = container.querySelector('ahi-button');
const banner = container.querySelector('ahi-banner');
button.addEventListener('click', () => banner.show());
</script>
<style>
.banner-countdown ahi-banner {
margin-top: var(--ahi-space-4);
}
</style>
Toast notifications
To display a banner as a toast notification, or “toast”, create the banner and call its
toast() method. This will move the banner out of its position in the DOM and into
the toast stack where it will be shown. Once dismissed, it
will be removed from the DOM completely. To reuse a toast, store a reference to it and call
toast() again later on.
You should always use the closable attribute so users can dismiss the notification. It’s also
common to set a reasonable duration when the notification doesn’t require acknowledgement.
<div class="banner-toast">
<ahi-button>Show Toast</ahi-button>
<ahi-banner variant="success" title="John Doe has been saved" duration="3000" closable>
This toast will automatically hide itself after three seconds, unless you interact with it.
</ahi-banner>
</div>
<script>
const container = document.querySelector('.banner-toast');
const button = container.querySelector('ahi-button');
const banner = container.querySelector('ahi-banner');
button.addEventListener('click', () => banner.toast());
</script>
Creating toasts imperatively
For convenience, you can create a utility that emits toast notifications with a function call rather than
composing them in your HTML. To do this, generate the banner with JavaScript, append it to the body, and
call the toast() method as shown in the example below.
<div class="banner-imperative-toast">
<ahi-button>Create Toast</ahi-button>
</div>
<script>
const container = document.querySelector('.banner-imperative-toast');
const button = container.querySelector('ahi-button');
let count = 0;
// Always escape HTML for text arguments!
function escapeHtml(html) {
const div = document.createElement('div');
div.textContent = html;
return div.innerHTML;
}
// Custom function to emit toast notifications
function notify(message, variant = 'success', duration = 3000) {
const banner = Object.assign(document.createElement('ahi-banner'), {
variant,
closable: true,
duration: duration,
innerHTML: escapeHtml(message)
});
document.body.append(banner);
return banner.toast();
}
button.addEventListener('click', () => {
notify(`This is custom toast #${++count}`);
});
</script>
The toast stack
The toast stack is a fixed position singleton element created and managed internally by the banner component. It will be added and removed from the DOM as needed when toasts are shown. When more than one toast is visible, they will stack vertically in the toast stack.
By default, the toast stack is positioned at the top-right of the viewport. You can change its position by
targeting .ahi-toast-stack in your stylesheet. To make toasts appear at the top-left of the
viewport, for example, use the following styles.
.ahi-toast-stack {
left: 0;
right: auto;
}
Importing
To import this component using a script tag:
<script type="module" src="/path/to/azalea-kit-ui/dist/components/banner/banner.js"></script>
To import this component using a bundler:
import '@azaleahealth/azalea-kit-ui/dist/components/banner/banner.js';
Slots
| Name | Description |
|---|---|
| (default) | The banner’s main content. |
Learn more about using slots.
Properties
| Name | Description | Type | Default | |
|---|---|---|---|---|
closable
|
Enables a close button that allows the user to dismiss the banner. |
boolean
|
false
|
|
duration
|
The length of time, in milliseconds, the banner will show before closing itself. If the user
interacts with the banner before it closes (e.g. moves the mouse over it), the timer will restart.
Defaults to Infinity, meaning the banner will not close on its own.
|
- |
Infinity
|
|
open
|
Indicates whether or not the banner is open. You can toggle this attribute to show and hide the
banner, or you can use the show() and hide() methods and this attribute
will reflect the banner’s open state.
|
boolean
|
false
|
|
title
|
The banner’s title. |
string
|
''
|
|
variant
|
The banner’s theme variant. |
'info' | 'success' | 'neutral' | 'warning' | 'critical'
|
'neutral'
|
|
countdown
|
Enables a countdown that indicates the remaining time the banner will be displayed. |
boolean
|
false
|
|
updateComplete |
A read-only promise that resolves when the component has finished updating. |
Learn more about properties and attributes.
Events
| Name | Description | Event Detail |
|---|---|---|
ahi-show |
Emitted when the banner opens. | - |
ahi-after-show |
Emitted after the banner opens and all animations are complete. | - |
ahi-hide |
Emitted when the banner closes. | - |
ahi-after-hide |
Emitted after the banner closes and all animations are complete. | - |
Learn more about events.
Methods
| Name | Description | Arguments |
|---|---|---|
show() |
Shows the banner. | - |
hide() |
Hides the banner | - |
toast() |
Displays the banner as a toast notification. This will move the banner out of its position in the DOM and, when dismissed, it will be removed from the DOM completely. By storing a reference to the banner, you can reuse it by calling this method again. The returned promise will resolve after the banner is hidden. | - |
Learn more about methods.
CSS Parts
| Name | Description |
|---|---|
base |
Deprecated. Use the banner part instead. |
banner |
The component’s outer wrapper. |
icon |
The container that wraps the banner’s icon. |
content-wrapper |
The container that wraps the content. |
title |
The container that wraps the banner’s heading/title. |
content |
The banner’s content. |
close-button |
The close button, an <ahi-icon-button>. |
close-button__base |
The close button’s exported base part. |
Learn more about customizing CSS parts.
Animations
| Name | Description |
|---|---|
banner.show |
The animation to use when showing the banner. |
banner.hide |
The animation to use when hiding the banner. |
Learn more about customizing animations.
Dependencies
This component automatically imports the following dependencies.
<ahi-icon><ahi-icon-button>