Interactive Overlay

Version	Tag	Status	API
v2	`<oc-interactive-overlay-v2>`	Stable, allowed for generation	InteractiveOverlayV2
v1	`<oc-interactive-overlay-v1>`	Deprecated, NOT allowed for generation	InteractiveOverlayV1

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

Overview (v2)

Source: ./src/components/interactive-overlay/v2/Overview.mdx

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

Story Default:

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

Source: ./src/components/interactive-overlay/v2/Configuration.mdx

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.

Story Default:

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

Source: ./src/components/interactive-overlay/v2/Migration.mdx

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:

v1 Attribute	v2 Equivalent	Notes
`base64-href`	`data-masked-ref` on the slotted element	Moved from component attribute to slotted element
`border-offset`	`--border-offset` CSS custom property	Moved from HTML attribute to CSS custom property
`border-radius`	`--border-radius` CSS custom property	Moved from HTML attribute to CSS custom property
`oc-aria-label`	`aria-label` on the slotted element	Use `aria-label` directly on the child element
`rel`	`rel` on the slotted `<a>` element	Moved from component attribute to slotted `<a>` element
`target`	`target` on the slotted `<a>` element	Moved from component attribute to slotted `<a>` element

Unchanged CSS custom properties

CSS Custom Property	Notes
`--border-radius`	No change
`--border-offset`	No change

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)

Source: ./src/components/interactive-overlay/v1/InteractiveOverlayV1.API.g.mdx

Interactive Overlay v1 API

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

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

Attributes / properties

Attribute	Type	Default	Required	Description
`border-radius`	`string`	`undefined`	no	Sets a custom border radius for the interactive overlay component.
`border-offset`	`string`	`undefined`	no	Sets a custom border offset for the interactive overlay component.
`base64-href`	`string`	`undefined`	no	Sets the base64 encoded link target of the interactive overlay component. 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 interactive overlay component. Note Only applies when base64Href is set.
`rel`	`string`	`undefined`	no	Sets the rel attribute of the interactive overlay component. Note Only applies when base64Href is set.
`oc-aria-label`	`string`	`undefined`	no	Sets the ARIA label of the interactive overlay component. Note Only applies when base64Href is set.

Slots

Slot	Required	Description
`default`	yes	Sets the content of the interactive overlay component. Add an `a` tag to make the interactive overlay component a link.

Events

Event	Detail type	Description
`oc-property-change`	`OcInteractiveOverlayV1Events["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
`--border-radius`	`undefined`	Sets a custom border radius
`--border-offset`	`undefined`	Sets a custom border offset

API v2

Source: ./src/components/interactive-overlay/v2/InteractiveOverlayV2.API.g.mdx

Interactive Overlay v2 API

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

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

Slots

Slot	Required	Description
`default`	yes	Accepts one of the following elements: - `<a href="#">` for a link - `<div data-masked-ref="Iw==" role="link" tabindex="0">` for a masked link - `<a href="#" data-masked-ref="Iw==">` for link switching If a non-interactive element is used, the interactive overlay will not have any styles or behaviors applied to it. For more information on interactive components, refer to the interactive component slots documentation.

Events

Event	Detail type	Description
`oc-property-change`	`OcInteractiveOverlayV2Events["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
`--border-radius`	`undefined`	Sets a custom border radius for the interactive overlay component.
`--border-offset`	`undefined`	Sets a custom border offset for the interactive overlay component.

Variations (v2)

Source: ./src/components/interactive-overlay/v2/Variations.mdx

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>

Story source (TypeScript, verbatim from Storybook)

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

Source: ./src/components/interactive-overlay/v1/Overview.mdx

Interactive overlay v1

Default variation

Story Default:

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

Configuration

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

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)

Source: ./src/components/interactive-overlay/v1/Configuration.mdx

Interactive overlay configuration

Story Default:

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

Source: ./src/components/interactive-overlay/v1/Variations.mdx

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>

Overview (v2)

Interactive overlay

Default variation

Configuration

Usage guidelines

Layout considerations

Accessibility

Configuration (v2)

Interactive overlay V2 configuration

Migration (v2)

Migration from Interactive Overlay v1 to v2

What's new

Native interactive elements in the slot

API changes

Removed attributes

Unchanged CSS custom properties

How to migrate

Migrate a basic interactive overlay

Migrate an interactive overlay with link behavior

Migrate an interactive overlay with masked link behavior

Migrate an interactive overlay with link switch behavior

Migrate an interactive overlay with a custom border radius

API v1 (v1, deprecated, not for generation)

Interactive Overlay v1 API

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

Attributes / properties

Slots

Events

CSS custom properties

API v2

Interactive Overlay v2 API

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

Slots

Events

CSS custom properties

Variations (v2)

Variations

Default

With button behavior

With link behavior

With masked link behavior

With link switch behavior

Demo: Header Icon

Interaction tests (InteractiveOverlayV2.interactions.stories.ts)

Should Have Pointer Events Set

Should Have No Pointer Events Set

V1 (v1, deprecated, not for generation)

Interactive overlay v1

Default variation

Configuration

Usage guidelines

Layout considerations

Accessibility

Use oc-aria-label

Button or masked link

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

Interactive overlay configuration

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

Variations

Default

With link behavior

With masked link behavior

With link switch behavior

Demo: border radius content

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

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

Use `oc-aria-label`