Interactive overlay

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

Overview (v2)

Interactive overlay

The interactive overlay component provides a way to make your content interactive. This component is useful in cases where you want to give your content a hover effect, an active state, or a link ability.

Default variation

<oc-interactive-overlay-v2>Per default, I am not interactive.</oc-interactive-overlay-v2>

Configuration

The interactive overlay component 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 interactive overlay 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.

Info

See the Interactive overlay UX documentation for detailed user experience guidelines.

Layout considerations

This component has potential visual overflow. When the border-offset property is used, the component extends beyond its bounding box and is clipped by parent containers with overflow: hidden. Ensure the parent container has sufficient padding to accommodate the component's full visual area.

Accessibility

The interactive overlay component relies on the slotted interactive element, so pass aria attributes directly if needed. Reference the built-in accessibility features guide for focus management and keyboard interactions.

Configuration (v2)

Interactive overlay V2 configuration

Configure the interactive overlay 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-interactive-overlay-v2>Per default, I am not interactive.</oc-interactive-overlay-v2>

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

Migration (v2)

Migration from Interactive Overlay v1 to v2

The oc-interactive-overlay component has been updated from oc-interactive-overlay-v1 to oc-interactive-overlay-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

Native interactive elements in the slot

In v2, the component no longer manages the interactive behavior (button/link) itself. Instead, you place a native interactive element (<button>, <a>, <a data-masked-ref> for masked links) directly in the default slot. This provides:

• Better accessibility with native semantics
• Full control over the interactive element's attributes (aria-label, rel, target, etc.)
• Native event support on the interactive element itself

API changes

Removed attributes

The following attributes have been removed and their functionality is now handled differently:

Unchanged CSS custom properties

How to migrate

Migrate a basic interactive overlay

For a basic interactive overlay that acts as a button, the main change is the tag name and moving the interactive element into the default slot as a native element.

<!-- From: -->
<oc-interactive-overlay-v1>Content</oc-interactive-overlay-v1>

<!-- To: -->
<oc-interactive-overlay-v2>
  <button>Content</button>
</oc-interactive-overlay-v2>

Migrate an interactive overlay with link behavior

<!-- From: -->
<oc-interactive-overlay-v1>
  <a href="#">Content</a>
</oc-interactive-overlay-v1>

<!-- To: -->
<oc-interactive-overlay-v2>
  <a href="#">Content</a>
</oc-interactive-overlay-v2>

Note: Only the tag name changes here — the slotted <a> element stays exactly the same.

Migrate an interactive overlay with masked link behavior

In v1, a masked link was created using the base64-href attribute. In v2, the masking is done via a data-masked-ref attribute on the interactive element inside the default slot.

<!-- From: -->
<oc-interactive-overlay-v1 base64-href="Iw==">Content</oc-interactive-overlay-v1>

<!-- To: -->
<oc-interactive-overlay-v2>
  <div data-masked-ref="Iw==" role="link" tabindex="0">Content</div>
</oc-interactive-overlay-v2>

Migrate an interactive overlay with link switch behavior

In v1, link switching was achieved using base64-href together with an <a> tag in the slot. In v2, the data-masked-ref attribute is placed directly on the <a> element.

<!-- From: -->
<oc-interactive-overlay-v1 base64-href="Iw==">
  <a href="#">Content</a>
</oc-interactive-overlay-v1>

<!-- To: -->
<oc-interactive-overlay-v2>
  <a href="#" data-masked-ref="Iw==">Content</a>
</oc-interactive-overlay-v2>

Migrate an interactive overlay with a custom border radius

<!-- From: -->
<oc-interactive-overlay-v1 border-radius="8px" border-offset="4px">
  Content
</oc-interactive-overlay-v1>

<!-- To: -->
<oc-interactive-overlay-v2 class="custom-border"> Content </oc-interactive-overlay-v2>
<style>
  .custom-border {
    --border-radius: 8px;
    --border-offset: 4px;
  }
</style>

API v1 (v1, deprecated, not for generation)

Interactive Overlay v1 API

API: <oc-interactive-overlay-v1> (InteractiveOverlayV1)

The interactive overlay component is a wrapper for an interactive element.

Attributes / properties

Slots

Events

CSS custom properties

API v2

Interactive Overlay v2 API

API: <oc-interactive-overlay-v2> (InteractiveOverlayV2)

The interactive overlay component is a wrapper for an interactive element.

Slots

Events

CSS custom properties

Variations (v2)

Variations

Listed below are the most common variations of the interactive overlay 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-interactive-overlay-variations--default · tags: components, interactive-overlay, 2, variations

The default configuration.

Args: defaultSlot=Per default, I am not interactive.

<oc-interactive-overlay-v2>Per default, I am not interactive.</oc-interactive-overlay-v2>

With button behavior

Story: components-interactive-overlay-variations--with-button-behavior · tags: components, interactive-overlay, 2, variations

The interactive overlay component as a button. Add a click event to see it in action.

Args: defaultSlot=<button>I act as a button. Add a click event to see me in action.</button>

<oc-interactive-overlay-v2>
<button>I act as a button. Add a click event to see me in action.</button>
</oc-interactive-overlay-v2>

With link behavior

Story: components-interactive-overlay-variations--with-link-behavior · tags: components, interactive-overlay, 2, variations

The interactive overlay component as a link. Search engines will detect the href.

Args: defaultSlot=<a href='#'>I act as a link. Search engines will see me as a link.</a>

<oc-interactive-overlay-v2><a href='#'>I act as a link. Search engines will see me as a link.</a></oc-interactive-overlay-v2>

With masked link behavior

Story: components-interactive-overlay-variations--with-masked-link-behavior · tags: components, interactive-overlay, 2, variations

The interactive overlay component as a masked link. Search engines will not detect the href.

Args: defaultSlot=(see snippet)

<oc-interactive-overlay-v2>
<div data-masked-ref='Iw==' role='link' tabindex='0'>I act as a masked link. Search engines will not see me as a link.</div>
</oc-interactive-overlay-v2>

With link switch behavior

Story: components-interactive-overlay-variations--with-link-switch-behavior · tags: components, interactive-overlay, 2, variations

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

Args: defaultSlot=<a href='#' data-masked-ref='Iw=='>I act as a link. Search engines will get another link than users.</a>

<oc-interactive-overlay-v2>
<a href='#' data-masked-ref='Iw=='>I act as a link. Search engines will get another link than users.</a>
</oc-interactive-overlay-v2>

Demo: Header Icon

Story: components-interactive-overlay-variations--demo-header-icon · tags: components, interactive-overlay, 2, variations

A demo of how to use the interactive overlay component to create a header icon with a badge.

<oc-interactive-overlay-v2>
<a
  href="/basket"
  class="my-header-icon oc-text-color-secondary oc-copy-50"
  aria-label="Warenkorb mit 9 Artikeln"
>
  <oc-icon-v1 size="100" type="basket"></oc-icon-v1>
  <oc-badge-v2 size="100" variant="primary">9</oc-badge-v2>
  <div>Warenkorb</div>
</a>
</oc-interactive-overlay-v2>
<style>
.my-header-icon {
  display: grid;
  justify-items: center;
}
.my-header-icon > oc-icon-v1 {
  position: relative;
  grid-area: 1 / 1;
}
.my-header-icon > oc-badge-v2 {
  position: relative;
  grid-area: 1 / 1;
  margin-top: 8px;
  margin-left: 16px;
}
.my-header-icon > div {
  max-width: 100%;
  text-wrap: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}
</style>

{
  name: "Demo: Header Icon",
  parameters: {
    controls: {
      disabled: true
    }
  },
  render() {
    return html`
      <oc-interactive-overlay-v2>
        <a
          href="/basket"
          class="my-header-icon oc-text-color-secondary oc-copy-50"
          aria-label="Warenkorb mit 9 Artikeln"
        >
          <oc-icon-v1 size="100" type="basket"></oc-icon-v1>
          <oc-badge-v2 size="100" variant="primary">9</oc-badge-v2>
          <div>Warenkorb</div>
        </a>
      </oc-interactive-overlay-v2>

      <style>
        .my-header-icon {
          display: grid;
          justify-items: center;
        }

        .my-header-icon > oc-icon-v1 {
          position: relative;
          grid-area: 1 / 1;
        }

        .my-header-icon > oc-badge-v2 {
          position: relative;
          grid-area: 1 / 1;
          margin-top: 8px;
          margin-left: 16px;
        }

        .my-header-icon > div {
          max-width: 100%;
          text-wrap: nowrap;
          overflow: hidden;
          text-overflow: ellipsis;
        }
      </style>
    `;
  }
}

Interaction tests (InteractiveOverlayV2.interactions.stories.ts)

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

Should Have Pointer Events Set

Story: components-interactive-overlay-interaction-tests--should-have-pointer-events-set · tags:

<oc-interactive-overlay-v2></oc-interactive-overlay-v2>

Should Have No Pointer Events Set

Story: components-interactive-overlay-interaction-tests--should-have-no-pointer-events-set · tags:

<oc-interactive-overlay-v2></oc-interactive-overlay-v2>

V1 (v1, deprecated, not for generation)

Interactive overlay v1

The interactive overlay component provides a way to make your content interactive. This component is useful in cases where you want to give your content a hover effect, an active state, or a link ability.

Default variation

<oc-interactive-overlay-v1>I act as a button. Add a click event to see me in action.</oc-interactive-overlay-v1>

Configuration

The interactive overlay component 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 interactive overlay 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.

Layout considerations

This component has potential visual overflow. When the border-offset property is used, the component extends beyond its bounding box and is clipped by parent containers with overflow: hidden. Ensure the parent container has sufficient padding to accommodate the component's full visual area.

Accessibility

The interactive overlay 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 interactive overlay 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.

Button or masked link

See Link behavior and masked links in the general accessibility documentation for how oc-aria-label is applied in these scenarios.

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

Interactive overlay configuration

Configure the interactive overlay 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-interactive-overlay-v1>I act as a button. Add a click event to see me in action.</oc-interactive-overlay-v1>

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

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

Variations

Listed below are the most common variations of the interactive overlay 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-interactive-overlay-v1-variations--default · tags: components, interactive-overlay, 1, variations

The default configuration.

Args: defaultSlot=I act as a button. Add a click event to see me in action.

<oc-interactive-overlay-v1>I act as a button. Add a click event to see me in action.</oc-interactive-overlay-v1>

With link behavior

Story: components-interactive-overlay-v1-variations--with-link-behavior · tags: components, interactive-overlay, 1, variations

The interactive overlay component as a link. Search engines will detect the href.

Args: defaultSlot=(see snippet)

<oc-interactive-overlay-v1>
  <!--The <a> tag should be placed inside the light DOM to improve SEO.--><a href='#'>I act as a link. Search engines will see me as a link.</a>
</oc-interactive-overlay-v1>

With masked link behavior

Story: components-interactive-overlay-v1-variations--with-masked-link-behavior · tags: components, interactive-overlay, 1, variations

The interactive overlay component as a masked link. Search engines will not detect the href.

Args: defaultSlot=I act as a masked link. Search engines will not see me as a link., base64-href=Iw==

<oc-interactive-overlay-v1 base64-href="Iw==">
  I act as a masked link. Search engines will not see me as a link.
</oc-interactive-overlay-v1>

With link switch behavior

Story: components-interactive-overlay-v1-variations--with-link-switch-behavior · tags: components, interactive-overlay, 1, variations

The interactive overlay 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-interactive-overlay-v1 base64-href="Iz92YXJpYW50PWZvbw==">
  <!--Search engines will detect the href, while users receive the Base64-encoded version.--><a href='#'>I act as a link. Search engines will get another link than users.</a>
</oc-interactive-overlay-v1>

Demo: border radius content

Story: components-interactive-overlay-v1-variations--demo-border-radius-content · tags: components, interactive-overlay, 1, variations

The interactive overlay component taking border radius and offset from the child.

Args: defaultSlot=(see snippet)

<oc-interactive-overlay-v1>
  <div class='oc-p-50' style='border-radius: 16px; outline-offset: 4px; background: lightyellow'>Content with 16px border radius and 4px outline-offset</div>
</oc-interactive-overlay-v1>