Icon Button
<ahi-icon-button> | AhiIconButton
Icon buttons are simple, icon-only buttons that can be used for actions and in toolbars.
You should always provide an label for assistive devices.
<ahi-icon-button name="settings" label="Settings"></ahi-icon-button>
Examples
Link buttons
Use the href attribute to convert the button to a link.
<ahi-icon-button name="settings" label="Settings" href="https://example.com" target="_blank"></ahi-icon-button>
States
Disabled
Use the disabled attribute to disable the icon button.
<ahi-icon-button name="settings" label="Settings" disabled></ahi-icon-button>
Showing and hiding content
When an icon button shows and hides a section of the page, set aria-expanded on the icon
button, set aria-controls to the section’s id, and update
aria-expanded each time the section opens or closes. The icon button passes both to the
<button> it renders, which is the element screen readers announce, so they say whether
the section is open. It passes aria-controls as a reference to the section itself, because an
id can’t be found from inside the shadow root, so the internal <button>’s
own aria-controls attribute reads empty in the browser’s developer tools. The
id must be in the same document or shadow root as the icon button. A section added to the page
after the icon button is linked the next time the icon button updates or takes focus.
An icon button that triggers an <ahi-dropdown> or
<ahi-popover> doesn’t need aria-expanded: the dropdown or popover sets it,
with aria-haspopup, as soon as it has rendered, and updates it as it opens and closes. That
holds for the icon button placed directly in the trigger or anchor slot; when it
is wrapped in another element there, the dropdown or popover sets them on the wrapper instead, and the icon
button gets neither.
<ahi-icon-button
class="icon-button-disclosure"
name="filter"
label="Filters"
aria-expanded="false"
aria-controls="icon-button-disclosure-filters"
></ahi-icon-button>
<div id="icon-button-disclosure-filters" hidden>
<p>Show only visits from the last 30 days.</p>
</div>
<script>
const iconButton = document.querySelector('.icon-button-disclosure');
const filters = document.getElementById('icon-button-disclosure-filters');
iconButton.addEventListener('click', () => {
const open = iconButton.getAttribute('aria-expanded') !== 'true';
iconButton.setAttribute('aria-expanded', String(open));
filters.hidden = !open;
});
</script>
With badges
Add an <ahi-badge> component in the icon button’s slot to add a badge to the icon.
Put the badge’s text in label, ideally at the start, and update label whenever the
badge text changes. The badge is visible inside the button, so WCAG 2.5.3 (Label in Name) needs its text in
the button’s accessible name: a speech-input user who says “click 99+” can only reach a button whose name
contains “99+”.
<ahi-icon-button name="bell" label="99+ unread notifications">
<ahi-badge>99+</ahi-badge>
</ahi-icon-button>
Importing
To import this component using a script tag:
<script type="module" src="/path/to/azalea-kit-ui/dist/components/icon-button/icon-button.js"></script>To import this component using a bundler:
import '@azaleahealth/azalea-kit-ui/dist/components/icon-button/icon-button.js';Slots
| Name | Description |
|---|---|
| (default) | Content to be displayed next to the icon. |
Learn more about using slots.
Properties
| Name | Description | Type | Default | |
|---|---|---|---|---|
disabled
|
Disables the button. |
boolean
|
false
|
|
download
|
Tells the browser to download the linked file as this filename. Only used when href is
set.
|
string | undefined
|
- | |
href
|
When set, the underlying button will be rendered as an <a> with this
href instead of a <button>.
|
string | undefined
|
- | |
name
|
The name of the icon to draw. |
string | undefined
|
- | |
hostTabIndex
tabindex
|
Mirrors a tabindex set on the host onto the internal control.
tabindex on a custom element governs the HOST, and does nothing to the focusable
element inside its shadow root — so <ahi-icon-button tabindex="-1"> used to leave
a live tab stop behind, because the internal <button> hardcoded
tabindex="0". Where the caller had also set aria-hidden="true" (the
pointer-only scroll controls in ahi-tab-group do exactly this) the result was a
keyboard user landing on a control screen readers are told does not exist — a WCAG 4.1.2 failure,
and the shape of bug that is invisible until something audits it. Found by the axe-core gate; see
CORE-782. Declared rather than read ad hoc so Lit re-renders when it changes. Absent, the internal
control keeps tabindex="0", so nothing changes for existing callers.
|
number | null
|
null
|
|
size
|
The size of the icon. |
'minor' | 'major' | 'spot'
|
'major'
|
|
color
|
The color of the icon. Can accept any valid CSS color value, including custom properties. |
string | undefined
|
- | |
label
|
A description that gets read by assistive devices. For optimal accessibility, you should always
include a label that describes what the icon button does. When you slot an
<ahi-badge>, include the badge’s text in the label, such as
99+ unread notifications, so the accessible name contains what is visible (WCAG 2.5.3
Label in Name).
|
string
|
''
|
|
target
|
Tells the browser where to open the link. Only used when href is set. |
'_blank' | '_parent' | '_self' | '_top' | undefined
|
- | |
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-blur |
Emitted when the icon button loses focus. | - |
ahi-focus |
Emitted when the icon button gains focus. | - |
Learn more about events.
Methods
| Name | Description | Arguments |
|---|---|---|
click() |
Simulates a click on the icon button. | - |
focus() |
Sets focus on the icon button. |
options: FocusOptions
|
blur() |
Removes focus from the icon button. | - |
Learn more about methods.
CSS Parts
| Name | Description |
|---|---|
base |
Deprecated. Use the icon-button part instead. |
icon-button |
The component’s outer wrapper. |
Learn more about customizing CSS parts.
Dependencies
This component automatically imports the following dependencies.
<ahi-icon>