@dreamworld/dw-icon-button

dw-icon-button

A LitElement-based Web Component that renders a circular icon button with Material Design ripple effects, hover/focus state overlays, tooltip support, and extended icon set via dw-icon.

Why not mwc-icon-button?

• Custom icon sets registered with dw-icon cannot be used with mwc-icon-button.
• mwc-icon-button cannot be resized easily.

---

1. User Guide

Installation & Setup

yarn add @dreamworld/dw-icon-button

import '@dreamworld/dw-icon-button/dw-icon-button.js';

The component renders icons using icon font classes. Include the relevant font stylesheets in your HTML:

<!-- Material Icons (filled) -->
<link href="https://fonts.googleapis.com/css?family=Material+Icons&display=block" rel="stylesheet" />

<!-- Material Icons Outlined (for iconFont="OUTLINED") -->
<link href="https://fonts.googleapis.com/css?family=Material+Icons+Outlined&display=block" rel="stylesheet" />

<!-- Material Symbols Outlined (for symbol attribute) -->
<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined" rel="stylesheet" />

---

Basic Usage

<!-- Default icon button -->
<dw-icon-button icon="perm_media"></dw-icon-button>

<!-- Disabled -->
<dw-icon-button icon="perm_media" disabled></dw-icon-button>

<!-- Primary color -->
<dw-icon-button icon="perm_media" primary></dw-icon-button>

<!-- Secondary color -->
<dw-icon-button icon="perm_media" secondary></dw-icon-button>

---

API Reference

Properties

Property	Attribute	Type	Default	Reflected	Description
icon	icon	String	—	No	Name of the icon to render via dw-icon
disabled	disabled	Boolean	false	Yes	Disables the button. Sets tabindex="-1" and stops click event propagation
iconSize	icon-size	Number	undefined	No	Icon size in pixels. When unset, dw-icon uses its own default (24px)
buttonSize	button-size	Number	undefined	No	Explicit button width/height in pixels. Padding is computed as (buttonSize - iconSize) / 2. When unset, the button fills its parent
primary	primary	Boolean	false	Yes	Renders the icon and ripple using --mdc-theme-primary
secondary	secondary	Boolean	false	Yes	Renders the icon and ripple using --mdc-theme-secondary
title	title	String	—	No	Tooltip text. Shown on mouseenter when the button is not disabled and not on a touch device
disabledTitle	disabled-title	String	—	No	Tooltip text. Shown on mouseenter only when disabled is true
tipExtraOptions	—	Object	{}	No	Additional options object merged into dw-tooltip's extraOptions for the title tooltip
tipOffset	—	Array	[0, 8]	No	Displacement of the tooltip from the button as [skidding, distance]. Applied to both the title and disabledTitle tooltips
iconFont	icon-font	String	—	Yes	Icon font variant. Accepted values: FILLED, OUTLINED
symbol	symbol	Boolean	false	Yes	When true, renders using the Material Symbols font instead of Material Icons
placement	placement	String	'top'	No	Tooltip position relative to the button. Accepts: top, bottom, left, right, with optional -start or -end suffix (e.g. top-start, left-end)

Tooltip note: title and disabledTitle are independent. Set both to show a tooltip in both enabled and disabled states.

Methods

Method	Signature	Description
focus	focus(): void	Programmatically focuses the internal <button> element

Events

No custom events are dispatched by this component. Standard DOM events (click, mousedown, mouseup, etc.) propagate from the host element normally, except when disabled is true — in that case, click events on the internal wrapper are stopped via stopImmediatePropagation.

Slots

Not supported. The component renders dw-icon internally within shadow DOM. Light DOM (slot) content is not accepted.

---

CSS Custom Properties

Property	Default	Description
--dw-icon-color	(from dw-icon)	Icon color in the default state
--dw-icon-color-active	rgba(0, 0, 0, 0.87)	Icon color when the button is focused
--dw-icon-color-disabled	(from dw-icon)	Icon color when disabled is true
--dw-icon-button-background	transparent	Background color of the button element
--dw-icon-button-padding	12px	Button padding. Automatically overridden when buttonSize is set
--mdc-theme-primary	—	Applied to icon color and ripple when primary attribute is set
--mdc-theme-secondary	—	Applied to icon color and ripple when secondary attribute is set
--mdc-theme-on-surface	—	Color used for hover/focus state overlays and ripple

/* Example: custom-colored icon button */
dw-icon-button {
  --dw-icon-color: #6200ee;
  --dw-icon-color-active: #3700b3;
  --dw-icon-button-background: #f5f5f5;
}

---

Sizing

To size the button container using CSS (without the buttonSize property), set width and height directly on the element:

dw-icon-button {
  width: 48px;
  height: 48px;
}

To use buttonSize for self-contained sizing with automatic padding:

<!-- 48px button with 24px icon → padding = (48 - 24) / 2 = 12px -->
<dw-icon-button icon="more_vert" buttonSize="48" iconSize="24"></dw-icon-button>

---

Advanced Usage

Tooltip on enabled button

<dw-icon-button
  icon="more_vert"
  .title=${"More options"}
  .placement=${"bottom"}
></dw-icon-button>

Tooltip on disabled button

<dw-icon-button
  icon="more_vert"
  disabled
  .disabledTitle=${"This action is unavailable"}
  .placement=${"bottom"}
></dw-icon-button>

Tooltip in both states

<dw-icon-button
  icon="more_vert"
  .title=${"More options"}
  .disabledTitle=${"This action is unavailable"}
  .placement=${"top"}
></dw-icon-button>

Custom tooltip delay via tipExtraOptions

<dw-icon-button
  icon="info"
  .title=${"Help"}
  .tipExtraOptions=${{ delay: [200, 0] }}
></dw-icon-button>

Custom tooltip offset via tipOffset

<dw-icon-button
  icon="info"
  .title=${"Help"}
  .tipOffset=${[0, 12]}
></dw-icon-button>

Material Symbols (outlined)

<dw-icon-button
  icon="signal_wifi_statusbar_not_connected"
  iconFont="OUTLINED"
  symbol
  iconSize="48"
></dw-icon-button>

Custom SVG icons (registered via DwIcon.addIcons)

import { DwIcon } from '@dreamworld/dw-icon/dw-icon.js';
import { svg } from 'lit';

DwIcon.addIcons({
  my_custom_icon: svg`<svg viewBox="0 0 24 24">...</svg>`,
});

<dw-icon-button icon="my_custom_icon"></dw-icon-button>

Programmatic focus

const btn = document.querySelector('dw-icon-button');
btn.focus();

---

2. Developer Guide / Architecture

Architecture Overview

Concern	Implementation
Base class	DwIconButton extends buttonFocus(LitElement)
Composition pattern	Mixin (buttonFocus from @dreamworld/pwa-helpers) layered over LitElement
DOM model	Shadow DOM only; no light DOM slots
Icon rendering	Delegates to <dw-icon> inside shadow DOM
Tooltip rendering	Conditionally renders <dw-tooltip> in shadow DOM; two independent instances managed for title and disabledTitle

Ripple State Machine

The ripple effect is driven entirely by CSS class toggling:

1. Entry (mousedown / touchstart): requestAnimationFrame adds ripple-entry class → CSS applies scale-in-ripple (225ms) and fade-in-ripple (75ms) keyframe animations on ::after.
2. A Promise (waitForEntryAnimation) resolves after 225ms, ensuring exit does not begin before entry completes.
3. Exit (mouseup / mouseleave / touchend): Awaits waitForEntryAnimation, then adds ripple-exit → CSS applies fade-out-ripple (250ms). After 250ms, both classes are removed.

Touch Device Handling

isTouchDevice() (from @dreamworld/web-util) is called:

• In the constructor to set _touchDevice property (reflected as touch-device attribute).
• In render() to suppress the title tooltip on touch devices.

The touch-device attribute disables hover overlays via the CSS rule:

:host(:not([disabled]):not([touch-device])) button:hover::before { opacity: 0.04; }

Focus Effect Suppression

To distinguish keyboard focus from pointer/touch focus:

• pointerdown sets _noFocusEffect = true → adds no-focus-effect attribute.
• blur resets _noFocusEffect = false → removes the attribute.

The attribute disables the focus overlay:

:host([no-focus-effect]) button:focus::before { opacity: 0; }

This ensures the focus ring only appears for keyboard navigation, not after mouse or touch interaction.

Disabled Click Interception

When disabled is true, the internal _onTooltipContainerClick handler on the wrapper <div> calls e.stopImmediatePropagation(). This prevents click events from reaching parent elements even though the underlying <button> has tabindex="-1" (not disabled attribute), which is necessary to allow the disabledTitle tooltip to still receive pointer events.

Module Entry Point

The package exports a single ES module:

main: "dw-icon-button.js"
type: "module"

The custom element dw-icon-button is registered via customElements.define at the end of dw-icon-button.js.