Icon buttons can be put into a loading state. This replaces the icon on the right with a spinner. This feature should be used for actions expected to complete asynchronously. During loading, the button has no interactive states and is not interactive.
You can replace the icon itself with other icons from our icon library. You can also change the icon color and the background color using the colors from our design system. But be sure to maintain a color contrast of at least 3:1.
The icon button 50 has an extended hitbox to fulfill the optimal size for touch targets. The icon button 25 meets minimum accessibility requirements of 24px as in WCAG 2.1 AA but is not recommended for touch input - so do not use it for important interactions.
You can use canvas, above or sticky as elevation levels for the icon button. The elevation level stacked is not supported. For canvas there is no shadow, the icon button appears flat and should be used on frame or canvas. For above there is a shadow and the icon button appears above other levels. For sticky there is also a shadow, the icon button appears above all other levels and is sticky.
Only the latest version (v3) is allowed for generation. Older versions are kept for reference and are deprecated.
Overview (v3)
Icon Button
The icon button component provides an interactive icon on a circular white background, with attributes for setting the icon, size, ARIA label, a disabled state and emitting a click event when interacted with.
The icon button is configurable, allowing you to tailor its features and appearance to your specific needs.
To explore all the available options and adjust the component, use the component configurator and see the changes affect the component in real-time.
Usage guidelines
Before integrating the icon button component into your project, make sure you have correctly installed the OTTO components package.
Look through the variations page for examples of possible component variations. Here, you can discover both common and specific variations that address different use cases.
This component has an extended hitbox.
The touch area extends beyond its bounding box, so it may be activated when the user clicks or taps outside the visible component area.
Ensure sufficient margin around the component to prevent unintended interactions with adjacent elements.
Accessibility
The icon button component comes with a set of built-in accessibility features to ensure a seamless experience for all users.
Use oc-aria-label
To make the icon button recognizable for screen readers, use the oc-aria-label attribute to provide clear and descriptive context information.
See the general accessibility documentation for guidance on using oc-aria-label, including how it works with link and masked link behavior.
Configure the icon button component with the controls below and see the changes live in the preview canvas.
Click the Show code button within the preview canvas to see the source code for the current component configuration.
Interactive configurator (Storybook controls); every option is listed in the API section of this file.
Migration (v3)
Migration from Icon Button v2 to v3
The oc-icon-button component has been updated from oc-icon-button-v2 to oc-icon-button-v3.
This migration guide provides step-by-step instructions to update your project to the latest version.
<!-- To: -->
<oc-icon-button-v3 icon="wishlist">
<a href="/wishlist"></a>
</oc-icon-button-v3>
API v1 (v1, deprecated, not for generation)
Icon Button v1 API
API: <oc-icon-button-v1> (IconButtonV1)
The Icon Button component provides an interactive icon on a circular white background, with attributes for setting the icon type, size, ARIA label, a disabled state and emitting a click event when interacted with.
Attributes / properties
Attribute
Type
Default
Required
Description
variant
"default" | "transparent" | "inverted"
"default"
no
Selects the style of icon button to be used.
Can be one of: default, transparent, and inverted.
size
"50" | "100" | "25"
"50"
no
Sets the size of the icon button. Can be one of: 25, 50, 100.
icon-type
icon name (428 values; see Icon list in `storybook/components/icon/README.md`)
yes
Sets the displayed icon. Find all available icons here.
transparent
boolean
false
no
Deprecated: Please use the variant property instead.
DEPRECATED: When enabled, sets the variant to transparent.
disabled
boolean
false
no
Toggles the state of the icon button between enabled and disabled. Set to true to disable the button and prevent user interaction.
loading
boolean
false
no
Toggles the state of the button between loading and not loading. Set to true to enable the loading state and display a loading animation.
elevated
boolean
undefined
no
Deprecated: Please use the elevation property instead.
DEPRECATED: When enabled, sets the elevation of the icon button to 200.
elevation
"100" | "200" | "300" | "0"
"0"
no
Sets the elevation level of the icon button. Can be one of: 0, 100, 200 or 300.
icon-color
string
undefined
no
Sets the color of the displayed icon. This overrides the default color in all cases except for the disabled state.
href
string
undefined
no
Sets the link target of the icon button.
base64-href
string
undefined
no
Sets the base64 encoded link target of the energy label. Use this attribute to prevent search engines from indexing the link target.
oc-aria-label
string
yes
Sets the ARIA label of the icon button.
Events
Event
Detail type
Description
click
PointerEvent
Clicking the icon button or pressing the Enter or Space key while the icon button is focused triggers the click event.
oc-property-change
OcIconButtonV1Events["oc-property-change"]
Whenever a property value changes, this event triggers. Use this event to track all property changes within the component.
Fired when the component is mounted to the DOM. The event is fired when the onMount hook of the component is called by the runtime.
oc-unmount
{ component: string; }
Fired when the component is unmounted from the DOM. The event is fired when the function returned by the onMount hook of the component is called by the runtime.
API v2 (v2, deprecated, not for generation)
Icon Button v2 API
API: <oc-icon-button-v2> (IconButtonV2)
The Icon Button component provides an interactive icon on a circular white background, with attributes for setting the icon type, size, ARIA label, a disabled state and emitting a click event when interacted with.
Fired when the component is mounted to the DOM. The event is fired when the onMount hook of the component is called by the runtime.
oc-unmount
{ component: string; }
Fired when the component is unmounted from the DOM. The event is fired when the function returned by the onMount hook of the component is called by the runtime.
API v3
Icon Button v3 API
API: <oc-icon-button-v3> (IconButtonV3)
The Icon Button component provides an interactive icon on a circular white background, with attributes for setting the icon type, size, ARIA label, a disabled state and emitting a click event when interacted with.
Selects the style of icon button to be used. secondary-on-color is deprecated, use secondary-over-color instead.
size
"50" | "100" | "25" | "75"
"50"
no
Sets the size of the icon button. Can be one of: 25, 50, 75, 100.
icon
icon name (428 values; see Icon list in `storybook/components/icon/README.md`)
yes
Sets the displayed icon. Find all available icons here.
label
string
undefined
no
When set a Tooltip with the label content will be displayed on hover.
disabled
boolean
false
no
Toggles the state of the icon button between enabled and disabled. Set to true to disable the button and prevent user interaction.
loading
boolean
false
no
Toggles the state of the button between loading and not loading. Set to true to enable the loading state and display a loading animation.
success
boolean
false
no
Sets the success state of the icon-button. This is a visual state that indicates a successful action. It does not change the functionality of the icon-button.
elevation-level
"canvas" | "above" | "sticky"
"canvas"
no
Sets the elevation level of the icon button. The elevation level determines the shadow and depth of the icon button. - canvas: no shadow, icon button appears flat, to be used on frame. - above: shadow, icon button appears above other levels. - sticky: shadow, icon button appears above all other levels and is sticky.
background-color
string
undefined
no
Deprecated: The background-color attribute is deprecated. Use the CSS variable --background-color instead.
Sets the background color of the icon button.
icon-color
string
undefined
no
Deprecated: The icon-color attribute is deprecated. Use the CSS variable --icon-color instead.
Sets the color of the displayed icon. This overrides the default color in all cases except for the disabled state.
base64-href
string
undefined
no
Sets the base64 encoded link target of the icon button. Use this attribute to prevent search engines from indexing the link target.
target
"_blank" | "_self" | "_parent" | "_top"
undefined
no
Sets the target attribute of the icon button.
Note Only applies when base64Href is set.
rel
string
undefined
no
Sets the rel attribute of the icon button.
Note Only applies when base64Href is set.
oc-aria-label
string
yes
Sets the ARIA label of the icon button.
Slots
Slot
Required
Description
default
no
Add an empty tag to change the default behavior of the icon button component.
- empty a tag: the icon button component behaves as a link (SEO relevant)
Events
Event
Detail type
Description
click
PointerEvent
Clicking the icon button or pressing the Enter or Space key while the icon button is focused triggers the click event.
oc-property-change
OcIconButtonV3Events["oc-property-change"]
Whenever a property value changes, this event triggers. Use this event to track all property changes within the component.
Fired when the component is mounted to the DOM. The event is fired when the onMount hook of the component is called by the runtime.
oc-unmount
{ component: string; }
Fired when the component is unmounted from the DOM. The event is fired when the function returned by the onMount hook of the component is called by the runtime.
CSS custom properties
Custom property
Default
Description
--background-color
undefined
Sets a custom background color through a CSS variable.
Note: The preferred way of using colors is via design tokens instead of hex values.
Note: This CSS variable only applies when using variant="custom-color-strong" or variant="custom-color-soft".
--icon-color
undefined
Sets a custom text color through a CSS variable.
Note: The preferred way of using colors is via design tokens instead of hex values.
Note: This CSS variable only applies when using variant="custom-color-strong" or variant="custom-color-soft".
Variations (v3)
Variations
Listed below are the most common variations of the icon button component as well as specific component variations for different use cases.
You can explore all available options using the component configurator, adjust the component to your needs, and see the changes live in a preview canvas.
Variation of the default configuration with a custom icon color set via the --icon-color CSS variable.
Args: variant=custom-color-soft, size=50, icon=otto-logo, oc-aria-label=Icon button example with the OTTO logo and a custom set icon color, --background-color=var(--oc-semantic-color-background-above), --icon-color=var(--oc-semantic-color-brand)
HTML
<oc-icon-button-v3 icon="otto-logo" variant="custom-color-soft" size="50" oc-aria-label="Icon button example with the OTTO logo and a custom set icon color" style="--background-color: var(--oc-semantic-color-background-above); --icon-color: var(--oc-semantic-color-brand)"></oc-icon-button-v3>
The icon button component as a link. Search engines will detect the href.
Args: icon=otto-logo, defaultSlot=<!--The <a> tag should be placed inside the light DOM to improve SEO.--><a href='#' aria-label='Link icon button'></a>
<oc-icon-button-v3 icon="otto-logo">
<!--The <a> tag should be placed inside the light DOM to improve SEO.--><a href='#' aria-label='Link icon button'></a>
</oc-icon-button-v3>
<oc-icon-button-v3 icon="wishlist" base64-href="Iz92YXJpYW50PWZvbw==">
<!--Search engines will detect the href, while users receive the Base64-encoded version.--><a href='#' aria-label='Icon Button'></a>
</oc-icon-button-v3>
Demonstration of the icon button with a label tooltip.
Args: size=100, variant=custom-color-strong, icon=info, --icon-color=#FFFFFF, oc-aria-label=Icon button of size 100 with custom background color, --background-color=#374BC8, label=This is a tooltip label
HTML
<oc-icon-button-v3 icon="info" size="100" variant="custom-color-strong" oc-aria-label="Icon button of size 100 with custom background color" label="This is a tooltip label" style="--icon-color: #FFFFFF; --background-color: #374BC8"></oc-icon-button-v3>
The icon button is highly configurable, allowing you to tailor its features and appearance to your specific needs.
To explore all the available options and adjust the component, use the component configurator and see the changes affect the component in real-time.
Usage guidelines
Before integrating the Icon Button component into your project, make sure you have correctly installed the OTTO components package.
Look through the variations page for examples of possible component variations. Here, you can discover both common and specific variations that address different use cases.
Layout considerations
This component has an extended hitbox.
The touch area extends beyond its bounding box, so it may be activated when the user clicks or taps outside the visible component area.
Ensure sufficient margin around the component to prevent unintended interactions with adjacent elements.
Accessibility
ARIA label
The icon button component should provide an accessible name with the context or action of the icon button.
Therefore is it necessary to set the oc-aria-label attribute in order to make the icon button accessible for assistive technology.
V1/Configuration (v1, deprecated, not for generation)
Icon Button configuration
Configure the Icon Button component with the controls below and see the changes live in the preview canvas.
Click the Show code button within the preview canvas to see the source code for the current component configuration.
<oc-icon-button-v1
icon-type="wishlist"
oc-aria-label="Icon button to test base64-href handling"
base64-href="L2Zvbw=="
></oc-icon-button-v1>
Story source (TypeScript, verbatim from Storybook)
{
render() {
return html`<oc-icon-button-v1
icon-type="wishlist"
oc-aria-label="Icon button to test base64-href handling"
base64-href="L2Zvbw=="
></oc-icon-button-v1>`;
},
async play({
canvasElement
}) {
const ocIconButton = canvasElement.getElementsByTagName("oc-icon-button-v1").item(0)!;
ocIconButton.focus();
await tick();
// instead of the div element there should now be an anchor element
const linkElement = ocIconButton.shadowRoot!.children.item(0)! as HTMLAnchorElement;
await expect(linkElement.tagName).toBe("A");
// anchor element inside the shadow root should have the correct href attribute
await expect(linkElement.getAttribute("href")).toBe(`/foo`);
// anchor element inside the shadow root should have the same fully href as the host
await expect(ocIconButton.href).toBe(`${window.location.origin}/foo`);
await expect(linkElement.href).toBe(`${window.location.origin}/foo`);
}
}
V1/Variations (v1, deprecated, not for generation)
Variations
Listed below are the most common variations of the Icon Button component as well as specific component variations for different use cases.
You can explore all available options using the component configurator, adjust the component to your needs, and see the changes live in a preview canvas.
Variation of the default configuration with a custom icon color.
Args: size=50, icon-type=otto-logo, oc-aria-label=Icon button example with the OTTO logo and a custom set icon color, icon-color=var(--oc-semantic-color-brand)
<oc-icon-button-v1 icon-type="otto-logo" size="50" oc-aria-label="Icon button example with the OTTO logo and a custom set icon color" icon-color="var(--oc-semantic-color-brand)"></oc-icon-button-v1>
The icon button component provides an interactive icon on a circular white background, with attributes for setting the icon, size, ARIA label, a disabled state and emitting a click event when interacted with.
The icon button is configurable, allowing you to tailor its features and appearance to your specific needs.
To explore all the available options and adjust the component, use the component configurator and see the changes affect the component in real-time.
Usage guidelines
Before integrating the icon button component into your project, make sure you have correctly installed the OTTO components package.
Look through the variations page for examples of possible component variations. Here, you can discover both common and specific variations that address different use cases.
This component has an extended hitbox.
The touch area extends beyond its bounding box, so it may be activated when the user clicks or taps outside the visible component area.
Ensure sufficient margin around the component to prevent unintended interactions with adjacent elements.
Accessibility
The icon button component comes with a set of built-in accessibility features to ensure a seamless experience for all users.
Use oc-aria-label
To make the icon button recognizable for screen readers, use the oc-aria-label attribute to provide clear and descriptive context information.
See the general accessibility documentation for guidance on using oc-aria-label, including how it works with link and masked link behavior.
V2/Configuration (v2, deprecated, not for generation)
Icon button configuration
Configure the icon button component with the controls below and see the changes live in the preview canvas.
Click the Show code button within the preview canvas to see the source code for the current component configuration.
<oc-icon-button-v2
icon="wishlist"
oc-aria-label="Icon button to test base64-href handling"
base64-href="L2Zvbw=="
></oc-icon-button-v2>
Story source (TypeScript, verbatim from Storybook)
{
render() {
return html`<oc-icon-button-v2
icon="wishlist"
oc-aria-label="Icon button to test base64-href handling"
base64-href="L2Zvbw=="
></oc-icon-button-v2>`;
},
async play({
canvasElement
}) {
const ocIconButton = canvasElement.getElementsByTagName("oc-icon-button-v2").item(0)!;
ocIconButton.focus();
await tick();
// instead of the div element there should now be an anchor element
const linkElement = ocIconButton.shadowRoot!.children.item(0)! as HTMLAnchorElement;
await expect(linkElement.tagName).toBe("A");
// anchor element inside the shadow root should have the correct href attribute
await expect(linkElement.getAttribute("href")).toBe(`/foo`);
// anchor element inside the shadow root should have the same fully href as the host
await expect(ocIconButton.href).toBe(`${window.location.origin}/foo`);
await expect(linkElement.href).toBe(`${window.location.origin}/foo`);
}
}
V2/Migration (v2, deprecated, not for generation)
Migration from Icon Button v1 to v2
The oc-icon-button component has been updated from oc-icon-button-v1 to oc-icon-button-v2.
This migration guide provides step-by-step instructions to update your project to the latest version.
The new elevation attribute provides more granular control over the button's elevation level with values 100, 200, and 300.
API changes
Removed attributes
v1 Attribute
v2 Equivalent
Notes
elevated
elevation="200"
Changed to granular elevation system
transparent
variant="transparent"
Renamed to variant
variant="inverted"
variant="inverted-transparent"
Renamed for clarity
icon-type="wishlist"
icon="wishlist"
Shortened attribute name
How to migrate
The oc-icon-button-v2 removes the deprecated properties elevated and transparent. Additionally, it renames the variant inverted to inverted-transparent, and the property icon-type to icon.
<!-- To: -->
<oc-icon-button-v2 icon="close" variant="transparent"></oc-icon-button-v2>
V2/Variations (v2, deprecated, not for generation)
Variations
Listed below are the most common variations of the icon button component as well as specific component variations for different use cases.
You can explore all available options using the component configurator, adjust the component to your needs, and see the changes live in a preview canvas.
Variation of the default configuration with a custom icon color.
Args: size=50, icon=otto-logo, oc-aria-label=Icon button example with the OTTO logo and a custom set icon color, icon-color=var(--oc-semantic-color-brand)
<oc-icon-button-v2 icon="otto-logo" size="50" oc-aria-label="Icon button example with the OTTO logo and a custom set icon color" icon-color="var(--oc-semantic-color-brand)"></oc-icon-button-v2>
The icon button component as a link. Search engines will detect the href.
Args: icon=otto-logo, defaultSlot=<!--The <a> tag should be placed inside the light DOM to improve SEO.--><a href='#' aria-label='Link icon button'></a>
<oc-icon-button-v2 icon="otto-logo">
<!--The <a> tag should be placed inside the light DOM to improve SEO.--><a href='#' aria-label='Link icon button'></a>
</oc-icon-button-v2>
<oc-icon-button-v2 icon="wishlist" base64-href="Iz92YXJpYW50PWZvbw==">
<!--Search engines will detect the href, while users receive the Base64-encoded version.--><a href='#' aria-label='Icon Button'></a>
</oc-icon-button-v2>
