Icon Button

Version	Tag	Status	API
v3	`<oc-icon-button-v3>`	Stable, allowed for generation	IconButtonV3
v2	`<oc-icon-button-v2>`	Deprecated, NOT allowed for generation	IconButtonV2
v1	`<oc-icon-button-v1>`	Deprecated, NOT allowed for generation	IconButtonV1

Only the latest version (v3) is allowed for generation. Older versions are kept for reference and are deprecated.

Overview (v3)

Source: ./src/components/icon-button/v3/Overview.mdx

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.

Default variation

Story Default:

<oc-icon-button-v3 icon="wishlist" oc-aria-label="Default icon button component"></oc-icon-button-v3>

Configuration

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.

Info

See the Icon Button UX documentation for detailed user experience guidelines.

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

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.

Configuration (v3)

Source: ./src/components/icon-button/v3/Configuration.mdx

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.

Story Default:

<oc-icon-button-v3 icon="wishlist" oc-aria-label="Default icon button component"></oc-icon-button-v3>

Interactive configurator (Storybook controls); every option is listed in the API section of this file.

Migration (v3)

Source: ./src/components/icon-button/v3/Migration.mdx

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.

Skip to:

What's new
API changes
How to migrate

What's new

The oc-icon-button-v3 includes a built-in tooltip via the label attribute:

<oc-icon-button-v3 icon="wishlist" label="Add to wishlist"></oc-icon-button-v3>

New variants

Additional styling variants are available for different use cases.

API changes

Removed attributes

v2 Attribute	v3 Equivalent	Notes
`elevation="100"`	`elevation-level="canvas"`	Renamed to semantic values
`elevation="200"`	`elevation-level="above"`	Renamed to semantic values
`elevation="300"`	`elevation-level="sticky"`	Renamed to semantic values
`href`	Use an `<a>` tag inside the default slot	Moved to slot for better SEO

How to migrate

The oc-icon-button-v3 removes the deprecated properties elevation and href. Additionally, it brings several new variants and a built-in tooltip.

Migrate a basic icon button

<!-- From: -->
<oc-icon-button-v2 icon="wishlist" elevation="200"></oc-icon-button-v2>

<!-- To: -->
<oc-icon-button-v3 icon="wishlist" elevation-level="above"></oc-icon-button-v3>

Migrate an icon button with href

<!-- From: -->
<oc-icon-button-v2 icon="wishlist" href="/wishlist"></oc-icon-button-v2>

<!-- To: -->
<oc-icon-button-v3 icon="wishlist">
  <a href="/wishlist"></a>
</oc-icon-button-v3>

API v1 (v1, deprecated, not for generation)

Source: ./src/components/icon-button/v1/IconButtonV1.API.g.mdx

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. Refer to the Events documentation for more information.
`oc-mount`	`{ component: string; }`	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)

Source: ./src/components/icon-button/v2/IconButtonV2.API.g.mdx

Icon Button v2 API

API: `<oc-icon-button-v2>` (IconButtonV2)

Attributes / properties

Attribute	Type	Default	Required	Description
`variant`	`"default" \| "transparent" \| "inverted-transparent"`	`"default"`	no	Selects the style of icon button to be used. Can be one of: `default`, `transparent`, and `inverted-transparent`.
`size`	`"50" \| "100" \| "25"`	`"50"`	no	Sets the size of the icon button. Can be one of: 25, 50, 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.
`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.
`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	Deprecated: Use an `a` tag in the default slot instead. Visit SEO optimization techniques for more information. ~~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.
`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 card 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`	`OcIconButtonV2Events["oc-property-change"]`	Whenever a property value changes, this event triggers. Use this event to track all property changes within the component. Refer to the Events documentation for more information.
`oc-mount`	`{ component: string; }`	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

Source: ./src/components/icon-button/v3/IconButtonV3.API.g.mdx

Icon Button v3 API

API: `<oc-icon-button-v3>` (IconButtonV3)

Attributes / properties

Attribute	Type	Default	Required	Description
`variant`	`"primary" \| "secondary" \| "secondary-on-color" \| "secondary-over-color" \| "tertiary" \| "custom-color-strong" \| "custom-color-soft" \| "transparent" \| "transparent-inverted"`	`"secondary-over-color"`	no	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. Refer to the Events documentation for more information.
`oc-mount`	`{ component: string; }`	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)

Source: ./src/components/icon-button/v3/Variations.mdx

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.

Default

Story: components-icon-button-variations--default · tags: components

The default configuration uses the icon=wishlist and size=50.

Args: oc-aria-label=Default icon button component

<oc-icon-button-v3 icon="wishlist" oc-aria-label="Default icon button component"></oc-icon-button-v3>

Transparent 75

Story: components-icon-button-variations--icon-button-75-transparent · tags: components

The transparent variant uses no background color for the icon button.

Args: size=75, variant=transparent, icon=wishlist, oc-aria-label=Icon button of size 75 and variant transparent

<oc-icon-button-v3 icon="wishlist" size="75" variant="transparent" oc-aria-label="Icon button of size 75 and variant transparent"></oc-icon-button-v3>

Transparent-Inverted 75

Story: components-icon-button-variations--icon-button-75-inverted · tags: components

The transparent-inverted variant features a white icon on a transparent background, suitable for dark backgrounds.

Args: size=75, variant=transparent-inverted, icon=wishlist, oc-aria-label=Icon button of size 75 and variant inverted

<oc-icon-button-v3 icon="wishlist" size="75" variant="transparent-inverted" oc-aria-label="Icon button of size 75 and variant inverted"></oc-icon-button-v3>

Transparent 50

Story: components-icon-button-variations--icon-button-50-transparent · tags: components

The transparent variant uses no background color for the icon button.

Args: size=50, variant=transparent, icon=wishlist, oc-aria-label=Icon button of size 50 and variant transparent

<oc-icon-button-v3 icon="wishlist" size="50" variant="transparent" oc-aria-label="Icon button of size 50 and variant transparent"></oc-icon-button-v3>

Transparent-Inverted 50

Story: components-icon-button-variations--icon-button-50-inverted · tags: components

The transparent-inverted variant features a white icon on a transparent background, suitable for dark backgrounds.

Args: size=50, variant=transparent-inverted, icon=wishlist, oc-aria-label=Icon button of size 50 and variant inverted

<oc-icon-button-v3 icon="wishlist" size="50" variant="transparent-inverted" oc-aria-label="Icon button of size 50 and variant inverted"></oc-icon-button-v3>

Success 100

Story: components-icon-button-variations--icon-button-100-success · tags: components

The success variant uses a green icon on a green background.

Args: size=100, success=true, icon=check, oc-aria-label=Icon button of size 100 and success state

<oc-icon-button-v3 icon="check" size="100" success oc-aria-label="Icon button of size 100 and success state"></oc-icon-button-v3>

Elevation level above

Story: components-icon-button-variations--icon-button-50-elevation-level-above · tags: components

Variation of the default configuration with an elevationLevel of above, adding a moderate shadow to the icon button.

Args: size=50, elevation-level=above, icon=wishlist, oc-aria-label=Icon button of size 50 with elevation-level above

<oc-icon-button-v3 icon="wishlist" size="50" elevation-level="above" oc-aria-label="Icon button of size 50 with elevation-level above"></oc-icon-button-v3>

Elevation level sticky

Story: components-icon-button-variations--icon-button-50-elevation-level-sticky · tags: components

Variation of the default configuration with an elevationLevel of sticky, adding a pronounced shadow to the icon button.

Args: size=50, elevation-level=sticky, icon=wishlist, oc-aria-label=Icon button of size 50 with elevation-level sticky

<oc-icon-button-v3 icon="wishlist" size="50" elevation-level="sticky" oc-aria-label="Icon button of size 50 with elevation-level sticky"></oc-icon-button-v3>

Disabled

Story: components-icon-button-variations--icon-button-50-disabled · tags: components

Variation of the default configuration with the disabled state enabled, preventing user interaction.

Args: size=50, disabled=true, icon=wishlist, oc-aria-label=Icon button of size 50 and variant disabled

<oc-icon-button-v3 icon="wishlist" size="50" disabled oc-aria-label="Icon button of size 50 and variant disabled"></oc-icon-button-v3>

Loading

Story: components-icon-button-variations--icon-button-loading · tags: components

Variation of the default configuration with the loading state enabled, showing a loading animation for the current process.

Args: size=50, icon=wishlist, oc-aria-label=Icon button with an animated loading spinner, loading=true

<oc-icon-button-v3 icon="wishlist" size="50" oc-aria-label="Icon button with an animated loading spinner" loading></oc-icon-button-v3>

Custom icon color

Story: components-icon-button-variations--icon-button-50-custom-icon-color · tags: components

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)

<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>

With link behavior

Story: components-icon-button-variations--with-link-behavior · tags: components

The icon button component as a link. Search engines will detect the href.

Args: icon=otto-logo, defaultSlot=<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>

With masked link behavior

Story: components-icon-button-variations--with-masked-link-behavior · tags: components

The icon button component as a masked link. Search engines will not detect the href.

Args: icon=otto-logo, base64-href=Iw==, oc-aria-label=Masked link icon button

<oc-icon-button-v3 icon="otto-logo" base64-href="Iw==" oc-aria-label="Masked link icon button"></oc-icon-button-v3>

With link switch behavior

Story: components-icon-button-variations--with-link-switch-behavior · tags: components

The icon button component as a link with switch behavior. Search engines will detect the href, while users receive the Base64-encoded version.

Args: base64-href=Iz92YXJpYW50PWZvbw==, defaultSlot=(see snippet)

<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>

Demo: wishlist

Story: components-icon-button-variations--demo-wishlist · tags: components

<oc-icon-button-v3
  variant="custom-color-soft"
  icon="wishlist"
  oc-aria-label="Add to wishlist"
  style="--background-color: var(--oc-semantic-color-background-above);"
></oc-icon-button-v3>
<script>
  (() => {
    const iconButton = document.getElementsByTagName("oc-icon-button-v3")[0];
    iconButton.addEventListener("click", () => {
      iconButton.selected = !iconButton.selected;
      iconButton.icon = iconButton.selected ? "wishlist-active" : "wishlist";
      iconButton.iconColor = iconButton.selected
        ? "var(--oc-semantic-color-brand)"
        : "var(--oc-semantic-color-text-default)";
      iconButton.ocAriaLabel = iconButton.selected
        ? "Remove from wishlist"
        : "Add to wishlist";
    });
  })();
</script>

Story source (TypeScript, verbatim from Storybook)

{
  name: "Demo: wishlist",
  render() {
    return html`
      <oc-icon-button-v3
        variant="custom-color-soft"
        icon="wishlist"
        oc-aria-label="Add to wishlist"
        style="--background-color: var(--oc-semantic-color-background-above);"
      ></oc-icon-button-v3>
      <script>
        (() => {
          const iconButton = document.getElementsByTagName("oc-icon-button-v3")[0];
          iconButton.addEventListener("click", () => {
            iconButton.selected = !iconButton.selected;
            iconButton.icon = iconButton.selected ? "wishlist-active" : "wishlist";
            iconButton.iconColor = iconButton.selected
              ? "var(--oc-semantic-color-brand)"
              : "var(--oc-semantic-color-text-default)";
            iconButton.ocAriaLabel = iconButton.selected
              ? "Remove from wishlist"
              : "Add to wishlist";
          });
        })();
      </script>
    `;
  }
}

Demo: wishlist with animation

Story: components-icon-button-variations--demo-wishlist-with-animation · tags: components

Demonstration of the icon button with animated icon

<oc-icon-button-v3
  variant="custom-color-soft"
  icon="wishlist"
  oc-aria-label="Add to wishlist"
  style="--background-color: var(--oc-semantic-color-background-above);"
></oc-icon-button-v3>
<script>
  (() => {
    const iconButton = document.getElementsByTagName("oc-icon-button-v3")[0];
    const iconName = "animated-wishlist-active-highlight";
    iconButton.addEventListener("click", () => {
      if (iconButton.getAttribute("icon") === iconName) {
        iconButton.setAttribute("style", "--icon-color:initial");
        iconButton.setAttribute("icon", "wishlist");
      } else {
        iconButton.setAttribute(
          "style",
          "--icon-color:var(--oc-semantic-color-background-brand)",
        );
        iconButton.setAttribute("icon", iconName);
      }
    });
  })();
</script>

Story source (TypeScript, verbatim from Storybook)

{
  name: "Demo: wishlist with animation",
  render() {
    return html`
      <oc-icon-button-v3
        variant="custom-color-soft"
        icon="wishlist"
        oc-aria-label="Add to wishlist"
        style="--background-color: var(--oc-semantic-color-background-above);"
      ></oc-icon-button-v3>
      <script>
        (() => {
          const iconButton = document.getElementsByTagName("oc-icon-button-v3")[0];
          const iconName = "animated-wishlist-active-highlight";
          iconButton.addEventListener("click", () => {
            if (iconButton.getAttribute("icon") === iconName) {
              iconButton.setAttribute("style", "--icon-color:initial");
              iconButton.setAttribute("icon", "wishlist");
            } else {
              iconButton.setAttribute(
                "style",
                "--icon-color:var(--oc-semantic-color-background-brand)",
              );
              iconButton.setAttribute("icon", iconName);
            }
          });
        })();
      </script>
    `;
  }
}

Demo: custom background color

Story: components-icon-button-variations--demo-custom-background-color · tags: components

Demonstration of the icon button with a custom background color set via the --background-color CSS variable.

Args: size=100, variant=custom-color-soft, icon=wishlist, oc-aria-label=Icon button of size 100 with custom background color, --background-color=#FFCCE2

<oc-icon-button-v3 icon="wishlist" size="100" variant="custom-color-soft" oc-aria-label="Icon button of size 100 with custom background color" style="--background-color: #FFCCE2"></oc-icon-button-v3>

Demo: custom background color and icon color

Story: components-icon-button-variations--demo-custom-background-color-icon-color · tags: components

Demonstration of the icon button with a custom background color and icon color set via CSS variables.

Args: size=100, variant=custom-color-strong, icon=speech-bubble-sparkles, --icon-color=#FFFFFF, oc-aria-label=Icon button of size 100 with custom background color, --background-color=#374BC8

<oc-icon-button-v3 icon="speech-bubble-sparkles" size="100" variant="custom-color-strong" oc-aria-label="Icon button of size 100 with custom background color" style="--icon-color: #FFFFFF; --background-color: #374BC8"></oc-icon-button-v3>

Story: components-icon-button-variations--demo-label-tooltip · tags: components

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

<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>

Demo: elevation levels

Story: components-icon-button-variations--demo-elevation-levels · tags: components

<style>
  .icon-button-grid {
    display: grid;
    grid-template-columns: repeat(4, max-content);
    gap: 32px 48px;
    align-items: center;
    margin: 32px 0;
  }
  .icon-button-grid-header {
    text-align: left;
  }
  .icon-button-grid-cell {
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: 16px;
  }
</style>
<div class="icon-button-grid">
  <div class="icon-button-grid-header"></div>
  <div class="icon-button-grid-header"></div>
  <div class="icon-button-grid-header oc-text-color-sale">above</div>
  <div class="icon-button-grid-header oc-text-color-sale">sticky</div>

  <div class="icon-button-grid-header oc-text-color-sale">secondary-over-color</div>
  <div class="icon-button-grid-cell">
    <oc-icon-button-v3
      icon="wishlist"
      size="100"
      variant="secondary-over-color"
      elevation-level="canvas"
      oc-aria-label="secondary-over-color canvas"
    ></oc-icon-button-v3>
  </div>
  <div class="icon-button-grid-cell">
    <oc-icon-button-v3
      icon="wishlist"
      size="100"
      variant="secondary-over-color"
      elevation-level="above"
      oc-aria-label="secondary-over-color above"
    ></oc-icon-button-v3>
  </div>
  <div class="icon-button-grid-cell">
    <oc-icon-button-v3
      icon="wishlist"
      size="100"
      variant="secondary-over-color"
      elevation-level="sticky"
      oc-aria-label="secondary-over-color sticky"
    ></oc-icon-button-v3>
  </div>
  <div class="icon-button-grid-header oc-text-color-sale">primary</div>
  <div class="icon-button-grid-cell">
    <oc-icon-button-v3
      icon="wishlist"
      size="100"
      variant="primary"
      elevation-level="canvas"
      oc-aria-label="primary canvas"
    ></oc-icon-button-v3>
  </div>
  <div class="icon-button-grid-cell">
    <oc-icon-button-v3
      icon="wishlist"
      size="100"
      variant="primary"
      elevation-level="above"
      oc-aria-label="primary above"
    ></oc-icon-button-v3>
  </div>
  <div class="icon-button-grid-cell">
    <oc-icon-button-v3
      icon="wishlist"
      size="100"
      variant="primary"
      elevation-level="sticky"
      oc-aria-label="primary sticky"
    ></oc-icon-button-v3>
  </div>
  <div class="icon-button-grid-header oc-text-color-sale">secondary</div>
  <div class="icon-button-grid-cell">
    <oc-icon-button-v3
      icon="wishlist"
      size="100"
      variant="secondary"
      elevation-level="canvas"
      oc-aria-label="secondary canvas"
    ></oc-icon-button-v3>
  </div>
  <div class="icon-button-grid-cell">
    <oc-icon-button-v3
      icon="wishlist"
      size="100"
      variant="secondary"
      elevation-level="above"
      oc-aria-label="secondary above"
    ></oc-icon-button-v3>
  </div>
  <div class="icon-button-grid-cell">
    <oc-icon-button-v3
      icon="wishlist"
      size="100"
      variant="secondary"
      elevation-level="sticky"
      oc-aria-label="secondary sticky"
    ></oc-icon-button-v3>
  </div>
  <div class="icon-button-grid-header oc-text-color-sale">tertiary</div>
  <div class="icon-button-grid-cell">
    <oc-icon-button-v3
      icon="wishlist"
      size="100"
      variant="tertiary"
      oc-aria-label="tertiary canvas"
    ></oc-icon-button-v3>
  </div>
  <div class="icon-button-grid-cell">n.a.</div>
  <div class="icon-button-grid-cell">n.a.</div>
  <div class="icon-button-grid-header oc-text-color-sale">transparent</div>
  <div class="icon-button-grid-cell">
    <oc-icon-button-v3
      icon="wishlist"
      size="100"
      variant="transparent"
      oc-aria-label="transparent canvas"
    ></oc-icon-button-v3>
  </div>
  <div class="icon-button-grid-cell">n.a.</div>
  <div class="icon-button-grid-cell">n.a.</div>
  <div class="icon-button-grid-header oc-text-color-sale">transparent-inverted</div>
  <div class="icon-button-grid-cell" style="background: #212121;">
    <oc-icon-button-v3
      icon="wishlist"
      size="100"
      variant="transparent-inverted"
      oc-aria-label="transparent-inverted canvas"
    ></oc-icon-button-v3>
  </div>
  <div class="icon-button-grid-cell">n.a.</div>
  <div class="icon-button-grid-cell">n.a.</div>
</div>

Story source (TypeScript, verbatim from Storybook)

{
  name: "Demo: elevation levels",
  render() {
    return html`
      <style>
        .icon-button-grid {
          display: grid;
          grid-template-columns: repeat(4, max-content);
          gap: 32px 48px;
          align-items: center;
          margin: 32px 0;
        }
        .icon-button-grid-header {
          text-align: left;
        }
        .icon-button-grid-cell {
          display: flex;
          flex-direction: column;
          align-items: center;
          gap: 16px;
        }
      </style>
      <div class="icon-button-grid">
        <div class="icon-button-grid-header"></div>
        <div class="icon-button-grid-header"></div>
        <div class="icon-button-grid-header oc-text-color-sale">above</div>
        <div class="icon-button-grid-header oc-text-color-sale">sticky</div>

        <div class="icon-button-grid-header oc-text-color-sale">secondary-over-color</div>
        <div class="icon-button-grid-cell">
          <oc-icon-button-v3
            icon="wishlist"
            size="100"
            variant="secondary-over-color"
            elevation-level="canvas"
            oc-aria-label="secondary-over-color canvas"
          ></oc-icon-button-v3>
        </div>
        <div class="icon-button-grid-cell">
          <oc-icon-button-v3
            icon="wishlist"
            size="100"
            variant="secondary-over-color"
            elevation-level="above"
            oc-aria-label="secondary-over-color above"
          ></oc-icon-button-v3>
        </div>
        <div class="icon-button-grid-cell">
          <oc-icon-button-v3
            icon="wishlist"
            size="100"
            variant="secondary-over-color"
            elevation-level="sticky"
            oc-aria-label="secondary-over-color sticky"
          ></oc-icon-button-v3>
        </div>
        <div class="icon-button-grid-header oc-text-color-sale">primary</div>
        <div class="icon-button-grid-cell">
          <oc-icon-button-v3
            icon="wishlist"
            size="100"
            variant="primary"
            elevation-level="canvas"
            oc-aria-label="primary canvas"
          ></oc-icon-button-v3>
        </div>
        <div class="icon-button-grid-cell">
          <oc-icon-button-v3
            icon="wishlist"
            size="100"
            variant="primary"
            elevation-level="above"
            oc-aria-label="primary above"
          ></oc-icon-button-v3>
        </div>
        <div class="icon-button-grid-cell">
          <oc-icon-button-v3
            icon="wishlist"
            size="100"
            variant="primary"
            elevation-level="sticky"
            oc-aria-label="primary sticky"
          ></oc-icon-button-v3>
        </div>
        <div class="icon-button-grid-header oc-text-color-sale">secondary</div>
        <div class="icon-button-grid-cell">
          <oc-icon-button-v3
            icon="wishlist"
            size="100"
            variant="secondary"
            elevation-level="canvas"
            oc-aria-label="secondary canvas"
          ></oc-icon-button-v3>
        </div>
        <div class="icon-button-grid-cell">
          <oc-icon-button-v3
            icon="wishlist"
            size="100"
            variant="secondary"
            elevation-level="above"
            oc-aria-label="secondary above"
          ></oc-icon-button-v3>
        </div>
        <div class="icon-button-grid-cell">
          <oc-icon-button-v3
            icon="wishlist"
            size="100"
            variant="secondary"
            elevation-level="sticky"
            oc-aria-label="secondary sticky"
          ></oc-icon-button-v3>
        </div>
        <div class="icon-button-grid-header oc-text-color-sale">tertiary</div>
        <div class="icon-button-grid-cell">
          <oc-icon-button-v3
            icon="wishlist"
            size="100"
            variant="tertiary"
            oc-aria-label="tertiary canvas"
          ></oc-icon-button-v3>
        </div>
        <div class="icon-button-grid-cell">n.a.</div>
        <div class="icon-button-grid-cell">n.a.</div>
        <div class="icon-button-grid-header oc-text-color-sale">transparent</div>
        <div class="icon-button-grid-cell">
          <oc-icon-button-v3
            icon="wishlist"
            size="100"
            variant="transparent"
            oc-aria-label="transparent canvas"
          ></oc-icon-button-v3>
        </div>
        <div class="icon-button-grid-cell">n.a.</div>
        <div class="icon-button-grid-cell">n.a.</div>
        <div class="icon-button-grid-header oc-text-color-sale">transparent-inverted</div>
        <div class="icon-button-grid-cell" style="background: #212121;">
          <oc-icon-button-v3
            icon="wishlist"
            size="100"
            variant="transparent-inverted"
            oc-aria-label="transparent-inverted canvas"
          ></oc-icon-button-v3>
        </div>
        <div class="icon-button-grid-cell">n.a.</div>
        <div class="icon-button-grid-cell">n.a.</div>
      </div>
    `;
  }
}

Interaction tests (IconButtonV3.interactions.stories.ts)

Interaction test stories (automated tests, not usage patterns).

Fire Interact Event

Story: components-icon-button-interaction-tests--fire-interact-event · tags: play-fn

<oc-icon-button-v3
  icon="wishlist"
  oc-aria-label="Icon button to test event firing"
></oc-icon-button-v3>

Story source (TypeScript, verbatim from Storybook)

{
  render: () => {
    return html` <oc-icon-button-v3
      icon="wishlist"
      oc-aria-label="Icon button to test event firing"
    ></oc-icon-button-v3>`;
  },
  play: async ({
    canvasElement
  }) => {
    const button = canvasElement.getElementsByTagName("oc-icon-button-v3").item(0)!;
    let interacted = 0;
    button.addEventListener("click", () => {
      interacted += 1;
    });
    await expect(interacted).toBe(0);
    await userEvent.click(button);
    await expect(interacted).toBe(1);
  }
}

Show Loading Spinner On Click

Story: components-icon-button-interaction-tests--show-loading-spinner-on-click · tags: play-fn

<oc-icon-button-v3
  icon="wishlist"
  oc-aria-label="Icon button to test the loading state"
></oc-icon-button-v3>

Story source (TypeScript, verbatim from Storybook)

{
  parameters: {
    // Disables Chromatic's snapshotting, as the spinner is animated und thus leads to diffs
    chromatic: {
      disableSnapshot: true
    }
  },
  render: () => {
    return html` <oc-icon-button-v3
      icon="wishlist"
      oc-aria-label="Icon button to test the loading state"
    ></oc-icon-button-v3>`;
  },
  play: async ({
    canvasElement
  }) => {
    const ocbutton = canvasElement.getElementsByTagName("oc-icon-button-v3").item(0)!;
    const button = getByShadowRole(canvasElement, "button");
    await userEvent.click(button);
    ocbutton.loading = true;
    await tick();
    const spinner = Array.from(button.childNodes).find(node => node.nodeName === "OC-SPINNER-V1");
    await expect(spinner).toBeTruthy();
    await expect(ocbutton.loading).toBe(true);
  }
}

V1 (v1, deprecated, not for generation)

Source: ./src/components/icon-button/v1/Overview.mdx

Icon Button v1

Important

This is a deprecated version of the icon button component. For the latest version, see the updated component documentation. Refer to this migration guide to update your project to the latest version.

Default variation

Story Default:

<oc-icon-button-v1 icon-type="wishlist" oc-aria-label="Default icon button component"></oc-icon-button-v1>

Configuration

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

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)

Source: ./src/components/icon-button/v1/Configuration.mdx

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.

Story Default:

<oc-icon-button-v1 icon-type="wishlist" oc-aria-label="Default icon button component"></oc-icon-button-v1>

Interactive configurator (Storybook controls); every option is listed in the API section of this file.

V1/Interaction tests (IconButtonV1.interactions.stories.ts)

Interaction test stories (automated tests, not usage patterns).

Fire Interact Event

Story: components-icon-button-v1-interaction-tests--fire-interact-event · tags: play-fn

<oc-icon-button-v1
  icon-type="wishlist"
  oc-aria-label="Icon button to test event firing"
></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 event firing"
    ></oc-icon-button-v1>`;
  },
  play: async ({
    canvasElement
  }) => {
    const button = canvasElement.getElementsByTagName("oc-icon-button-v1").item(0)!;
    let interacted = 0;
    button.addEventListener("click", () => {
      interacted += 1;
    });
    await expect(interacted).toBe(0);
    await userEvent.click(button);
    await expect(interacted).toBe(1);
  }
}

Show Loading Spinner On Click

Story: components-icon-button-v1-interaction-tests--show-loading-spinner-on-click · tags: play-fn

<oc-icon-button-v1
  icon-type="wishlist"
  oc-aria-label="Icon button to test the loading state"
></oc-icon-button-v1>

Story source (TypeScript, verbatim from Storybook)

{
  parameters: {
    // Disables Chromatic's snapshotting, as the spinner is animated und thus leads to diffs
    chromatic: {
      disableSnapshot: true
    }
  },
  render: () => {
    return html` <oc-icon-button-v1
      icon-type="wishlist"
      oc-aria-label="Icon button to test the loading state"
    ></oc-icon-button-v1>`;
  },
  play: async ({
    canvasElement
  }) => {
    const ocbutton = canvasElement.getElementsByTagName("oc-icon-button-v1").item(0)!;
    const button = getByShadowRole(canvasElement, "button");
    await new Promise(res => {
      setTimeout(res, 1000);
    });
    await userEvent.click(button);
    ocbutton.loading = true;
    await new Promise(res => {
      setTimeout(res, 1000);
    });
    const spinner = Array.from(button.childNodes).find(node => node.nodeName === "OC-SPINNER-V1");
    await expect(spinner).toBeTruthy();
    await expect(ocbutton.loading).toBe(true);
  }
}

Should Handle Base 64 Href

Story: components-icon-button-v1-interaction-tests--should-handle-base-64-href · tags: play-fn

<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)

Source: ./src/components/icon-button/v1/Variations.mdx

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.

Default

Story: components-icon-button-v1-variations--default · tags: components, icon-button, v1, variations

The default configuration uses the icon-type=wishlist and size=50.

Args: oc-aria-label=Default icon button component

<oc-icon-button-v1 icon-type="wishlist" oc-aria-label="Default icon button component"></oc-icon-button-v1>

Transparent

Story: components-icon-button-v1-variations--icon-button-50-transparent · tags: components, icon-button, v1, variations

The transparent variant uses no background color for the icon button.

Args: size=50, variant=transparent, icon-type=wishlist, oc-aria-label=Icon button of size 50 and variant transparent

<oc-icon-button-v1 icon-type="wishlist" size="50" variant="transparent" oc-aria-label="Icon button of size 50 and variant transparent"></oc-icon-button-v1>

Inverted

Story: components-icon-button-v1-variations--icon-button-50-inverted · tags: components, icon-button, v1, variations

The inverted variant features a white icon on a transparent background, suitable for dark backgrounds.

Args: size=50, variant=inverted, icon-type=wishlist, oc-aria-label=Icon button of size 50 and variant inverted

<oc-icon-button-v1 icon-type="wishlist" size="50" variant="inverted" oc-aria-label="Icon button of size 50 and variant inverted"></oc-icon-button-v1>

Elevation 100

Story: components-icon-button-v1-variations--icon-button-50-elevation-100 · tags: components, icon-button, v1, variations

Variation of the default configuration with an elevation of 100, adding a slight shadow to the icon button.

Args: size=50, elevation=100, icon-type=wishlist, oc-aria-label=Icon button of size 50 with elevation 100

<oc-icon-button-v1 icon-type="wishlist" size="50" elevation="100" oc-aria-label="Icon button of size 50 with elevation 100"></oc-icon-button-v1>

Elevation 200

Story: components-icon-button-v1-variations--icon-button-50-elevation-200 · tags: components, icon-button, v1, variations

Variation of the default configuration with an elevation of 100, adding a moderate shadow to the icon button.

Args: size=50, elevation=200, icon-type=wishlist, oc-aria-label=Icon button of size 50 with elevation 200

<oc-icon-button-v1 icon-type="wishlist" size="50" elevation="200" oc-aria-label="Icon button of size 50 with elevation 200"></oc-icon-button-v1>

Elevation 300

Story: components-icon-button-v1-variations--icon-button-50-elevation-300 · tags: components, icon-button, v1, variations

Variation of the default configuration with an elevation of 100, adding a pronounced shadow to the icon button.

Args: size=50, elevation=300, icon-type=wishlist, oc-aria-label=Icon button of size 50 with elevation 300

<oc-icon-button-v1 icon-type="wishlist" size="50" elevation="300" oc-aria-label="Icon button of size 50 with elevation 300"></oc-icon-button-v1>

Disabled

Story: components-icon-button-v1-variations--icon-button-50-disabled · tags: components, icon-button, v1, variations

Variation of the default configuration with the disabled state enabled, preventing user interaction.

Args: size=50, disabled=true, icon-type=wishlist, oc-aria-label=Icon button of size 50 and variant disabled

<oc-icon-button-v1 icon-type="wishlist" size="50" disabled oc-aria-label="Icon button of size 50 and variant disabled"></oc-icon-button-v1>

Loading

Story: components-icon-button-v1-variations--icon-button-loading · tags: components, icon-button, v1, variations

Variation of the default configuration with the loading state enabled, showing a loading animation for the current process.

Args: size=50, icon-type=wishlist, oc-aria-label=Icon button with an animated loading spinner, loading=true

<oc-icon-button-v1 icon-type="wishlist" size="50" oc-aria-label="Icon button with an animated loading spinner" loading></oc-icon-button-v1>

Custom icon color

Story: components-icon-button-v1-variations--icon-button-50-custom-icon-color · tags: components, icon-button, v1, variations

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>

V2 (v2, deprecated, not for generation)

Source: ./src/components/icon-button/v2/Overview.mdx

Icon button v2

Important

This is a deprecated version of the icon button component. For the latest version, see the updated component documentation. Refer to this migration guide to update your project to the latest version.

Default variation

Story Default:

<oc-icon-button-v2 icon="wishlist" oc-aria-label="Default icon button component"></oc-icon-button-v2>

Configuration

Usage guidelines

Info

See the Icon button UX documentation for detailed user experience guidelines.

Layout considerations

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`

V2/Configuration (v2, deprecated, not for generation)

Source: ./src/components/icon-button/v2/ConfigurationV2.mdx

Icon button configuration

Story Default:

<oc-icon-button-v2 icon="wishlist" oc-aria-label="Default icon button component"></oc-icon-button-v2>

Interactive configurator (Storybook controls); every option is listed in the API section of this file.

V2/Interaction tests (IconButtonV2.interactions.stories.ts)

Interaction test stories (automated tests, not usage patterns).

Fire Interact Event

Story: components-icon-button-v2-interaction-tests--fire-interact-event · tags: play-fn

<oc-icon-button-v2
  icon="wishlist"
  oc-aria-label="Icon button to test event firing"
></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 event firing"
    ></oc-icon-button-v2>`;
  },
  play: async ({
    canvasElement
  }) => {
    const button = canvasElement.getElementsByTagName("oc-icon-button-v2").item(0)!;
    let interacted = 0;
    button.addEventListener("click", () => {
      interacted += 1;
    });
    await expect(interacted).toBe(0);
    await userEvent.click(button);
    await expect(interacted).toBe(1);
  }
}

Show Loading Spinner On Click

Story: components-icon-button-v2-interaction-tests--show-loading-spinner-on-click · tags: play-fn

<oc-icon-button-v2
  icon="wishlist"
  oc-aria-label="Icon button to test the loading state"
></oc-icon-button-v2>

Story source (TypeScript, verbatim from Storybook)

{
  parameters: {
    // Disables Chromatic's snapshotting, as the spinner is animated und thus leads to diffs
    chromatic: {
      disableSnapshot: true
    }
  },
  render: () => {
    return html` <oc-icon-button-v2
      icon="wishlist"
      oc-aria-label="Icon button to test the loading state"
    ></oc-icon-button-v2>`;
  },
  play: async ({
    canvasElement
  }) => {
    const ocbutton = canvasElement.getElementsByTagName("oc-icon-button-v2").item(0)!;
    const button = getByShadowRole(canvasElement, "button");
    await userEvent.click(button);
    ocbutton.loading = true;
    await tick();
    const spinner = Array.from(button.childNodes).find(node => node.nodeName === "OC-SPINNER-V1");
    await expect(spinner).toBeTruthy();
    await expect(ocbutton.loading).toBe(true);
  }
}

Should Handle Base 64 Href

Story: components-icon-button-v2-interaction-tests--should-handle-base-64-href · tags: play-fn

<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)

Source: ./src/components/icon-button/v2/Migration.mdx

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.

Skip to:

What's new
API changes
How to migrate

What's new

Elevation system

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.

Migrate a basic icon button

<!-- From: -->
<oc-icon-button-v1 icon-type="wishlist" elevated></oc-icon-button-v1>

<!-- To: -->
<oc-icon-button-v2 icon="wishlist" elevation="200"></oc-icon-button-v2>

Migrate a transparent icon button

<!-- From: -->
<oc-icon-button-v1 icon-type="close" transparent></oc-icon-button-v1>

<!-- To: -->
<oc-icon-button-v2 icon="close" variant="transparent"></oc-icon-button-v2>

V2/Variations (v2, deprecated, not for generation)

Source: ./src/components/icon-button/v2/Variations.mdx

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.

Default

Story: components-icon-button-v2-variations--default · tags: components

The default configuration uses the icon=wishlist and size=50.

Args: oc-aria-label=Default icon button component

<oc-icon-button-v2 icon="wishlist" oc-aria-label="Default icon button component"></oc-icon-button-v2>

Transparent

Story: components-icon-button-v2-variations--icon-button-50-transparent · tags: components

The transparent variant uses no background color for the icon button.

Args: size=50, variant=transparent, icon=wishlist, oc-aria-label=Icon button of size 50 and variant transparent

<oc-icon-button-v2 icon="wishlist" size="50" variant="transparent" oc-aria-label="Icon button of size 50 and variant transparent"></oc-icon-button-v2>

Inverted transparent

Story: components-icon-button-v2-variations--icon-button-50-inverted-transparent · tags: components

The inverted-transparent variant features a white icon on a transparent background, suitable for dark backgrounds.

Args: size=50, variant=inverted-transparent, icon=wishlist, oc-aria-label=Icon button of size 50 and variant inverted-transparent

<oc-icon-button-v2 icon="wishlist" size="50" variant="inverted-transparent" oc-aria-label="Icon button of size 50 and variant inverted-transparent"></oc-icon-button-v2>

Elevation 100

Story: components-icon-button-v2-variations--icon-button-50-elevation-100 · tags: components

Variation of the default configuration with an elevation of 100, adding a slight shadow to the icon button.

Args: size=50, elevation=100, icon=wishlist, oc-aria-label=Icon button of size 50 with elevation 100

<oc-icon-button-v2 icon="wishlist" size="50" elevation="100" oc-aria-label="Icon button of size 50 with elevation 100"></oc-icon-button-v2>

Elevation 200

Story: components-icon-button-v2-variations--icon-button-50-elevation-200 · tags: components

Variation of the default configuration with an elevation of 100, adding a moderate shadow to the icon button.

Args: size=50, elevation=200, icon=wishlist, oc-aria-label=Icon button of size 50 with elevation 200

<oc-icon-button-v2 icon="wishlist" size="50" elevation="200" oc-aria-label="Icon button of size 50 with elevation 200"></oc-icon-button-v2>

Elevation 300

Story: components-icon-button-v2-variations--icon-button-50-elevation-300 · tags: components

Variation of the default configuration with an elevation of 100, adding a pronounced shadow to the icon button.

Args: size=50, elevation=300, icon=wishlist, oc-aria-label=Icon button of size 50 with elevation 300

<oc-icon-button-v2 icon="wishlist" size="50" elevation="300" oc-aria-label="Icon button of size 50 with elevation 300"></oc-icon-button-v2>

Disabled

Story: components-icon-button-v2-variations--icon-button-50-disabled · tags: components

Variation of the default configuration with the disabled state enabled, preventing user interaction.

Args: size=50, disabled=true, icon=wishlist, oc-aria-label=Icon button of size 50 and variant disabled

<oc-icon-button-v2 icon="wishlist" size="50" disabled oc-aria-label="Icon button of size 50 and variant disabled"></oc-icon-button-v2>

Loading

Story: components-icon-button-v2-variations--icon-button-loading · tags: components

Variation of the default configuration with the loading state enabled, showing a loading animation for the current process.

Args: size=50, icon=wishlist, oc-aria-label=Icon button with an animated loading spinner, loading=true

<oc-icon-button-v2 icon="wishlist" size="50" oc-aria-label="Icon button with an animated loading spinner" loading></oc-icon-button-v2>

Custom icon color

Story: components-icon-button-v2-variations--icon-button-50-custom-icon-color · tags: components

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>

With link behavior

Story: components-icon-button-v2-variations--with-link-behavior · tags: components

The icon button component as a link. Search engines will detect the href.

Args: icon=otto-logo, defaultSlot=<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>

With masked link behavior

Story: components-icon-button-v2-variations--with-masked-link-behavior · tags: components

The icon button component as a masked link. Search engines will not detect the href.

Args: icon=otto-logo, base64-href=Iw==, oc-aria-label=Masked link icon button

<oc-icon-button-v2 icon="otto-logo" base64-href="Iw==" oc-aria-label="Masked link icon button"></oc-icon-button-v2>

With link switch behavior

Story: components-icon-button-v2-variations--with-link-switch-behavior · tags: components

The icon button component as a link with switch behavior. Search engines will detect the href, while users receive the Base64-encoded version.

Args: base64-href=Iz92YXJpYW50PWZvbw==, defaultSlot=(see snippet)

<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>

Demo: Wishlist

Story: components-icon-button-v2-variations--demo-wishlist · tags: components

<oc-icon-button-v2 icon="wishlist" oc-aria-label="Add to wishlist"></oc-icon-button-v2>
<script>
  (() => {
    const iconButton = document.getElementsByTagName("oc-icon-button-v2")[0];
    iconButton.addEventListener("click", () => {
      iconButton.selected = !iconButton.selected;
      iconButton.icon = iconButton.selected ? "wishlist-active" : "wishlist";
      iconButton.iconColor = iconButton.selected ? "var(--oc-semantic-color-brand)" : "unset";
      iconButton.ocAriaLabel = iconButton.selected
        ? "Remove from wishlist"
        : "Add to wishlist";
    });
  })();
</script>

Story source (TypeScript, verbatim from Storybook)

{
  name: "Demo: Wishlist",
  render() {
    return html`
      <oc-icon-button-v2 icon="wishlist" oc-aria-label="Add to wishlist"></oc-icon-button-v2>
      <script>
        (() => {
          const iconButton = document.getElementsByTagName("oc-icon-button-v2")[0];
          iconButton.addEventListener("click", () => {
            iconButton.selected = !iconButton.selected;
            iconButton.icon = iconButton.selected ? "wishlist-active" : "wishlist";
            iconButton.iconColor = iconButton.selected ? "var(--oc-semantic-color-brand)" : "unset";
            iconButton.ocAriaLabel = iconButton.selected
              ? "Remove from wishlist"
              : "Add to wishlist";
          });
        })();
      </script>
    `;
  }
}

Overview (v3)

Icon Button

Default variation

Configuration

Usage guidelines

Layout considerations

Accessibility

Use oc-aria-label

Further reading

Configuration (v3)

Icon Button configuration

Migration (v3)

Migration from Icon Button v2 to v3

What's new

Built-in tooltip

New variants

API changes

Removed attributes

How to migrate

Migrate a basic icon button

Migrate an icon button with href

API v1 (v1, deprecated, not for generation)

Icon Button v1 API

API: <oc-icon-button-v1> (IconButtonV1)

Attributes / properties

Events

API v2 (v2, deprecated, not for generation)

Icon Button v2 API

API: <oc-icon-button-v2> (IconButtonV2)

Attributes / properties

Slots

Events

API v3

Icon Button v3 API

API: <oc-icon-button-v3> (IconButtonV3)

Attributes / properties

Slots

Events

CSS custom properties

Variations (v3)

Variations

Default

Transparent 75

Transparent-Inverted 75

Transparent 50

Transparent-Inverted 50

Success 100

Elevation level above

Elevation level sticky

Disabled

Loading

Custom icon color

With link behavior

With masked link behavior

With link switch behavior

Demo: wishlist

Demo: wishlist with animation

Demo: custom background color

Demo: custom background color and icon color

Demo: label tooltip

Demo: elevation levels

Interaction tests (IconButtonV3.interactions.stories.ts)

Fire Interact Event

Show Loading Spinner On Click

V1 (v1, deprecated, not for generation)

Icon Button v1

Default variation

Configuration

Usage guidelines

Layout considerations

Accessibility

ARIA label

Further reading

V1/Configuration (v1, deprecated, not for generation)

Icon Button configuration

V1/Interaction tests (IconButtonV1.interactions.stories.ts)

Fire Interact Event

Show Loading Spinner On Click

Should Handle Base 64 Href

V1/Variations (v1, deprecated, not for generation)

Use `oc-aria-label`

API: `<oc-icon-button-v1>` (IconButtonV1)

API: `<oc-icon-button-v2>` (IconButtonV2)

API: `<oc-icon-button-v3>` (IconButtonV3)

Use `oc-aria-label`