EWC icon-button Component

A button with a certain look and feel, displaying one of a set of given icons.

Overview

The ewc-icon-button component provides a standardized button for Eurostat web applications. It offers a consistent visual identity across Eurostat digital products.

Features

• Can be used on light or dark background
• Offers icons commonly used in visualisations
• Accessibility compliant
• It's state can be true (pressed), false (not pressed) or disabled (not focusable).
• Each state has it's own visual representation (incl. focus and hover effects).

Screenshot

API

Attributes

The following attributes are available and can be modified at runtime:

| Attributes | Properties | Default | Mandatory? | Description |----------------|------------|---------|------------|--------- | icon | | none | yes | Specifies the icon displayed in the button. one of: [close, linechart, barchart, dotplot, table, star, share, information, download, calendar, chevronleft, chevronright, squareshare] | background | | light | no | on which kind of background the button is used. one of: [light, dark, blue]. default is light. | state | state (set & get) | false | no | Specifies if the button is pressed or not pressed or disabled. tristate, one of [true,false,disabled] (see below for details about state) | size | | 32px | no | the width and height of the icon. | title | | none | no | Specifies a text that is displayed in a tooltip. If omitted, no tooltip is shown. | btn-aria-label | | "" | no | the aria-label of the button element inside the shadow DOM (not of the ewc-icon-button itself) | pressed-focusable | | false | no | if set to "true", a button that's pressed is also focusable. otherwise a pressed button is not focusable. | label | | "" | no | sets the text displayed in the button at the right side of the icon | use-config | | "" | no | specify the id of another config (see below for details) | tooltip-pos | | "below" | no | specify where the tooltip should appear - above, right, below or left of the button. one of: [above, right, below, left]. | | | | | Note: The convention is, to try to place it without covering other content. The preferred placement order is: below, above, right, left. | | | | | Example: If there is content which shouldn't be covered by the tooltip below, above and to the right of a button, place the tooltip on the left side. | tooltip-suppressed| | false | no | If true, tooltip is not displayed at all

Events

• action - keyborad-Enter/Space key and mouse-click are captured, prevented and instead one event "action" is dispatched.

Public functions

• toggle() - switches state between "true" and "false" as long as state is not "disabled".

Notes

• state

  • if set to "true", the button visually displays as being "pressed".
  • if set to "false" to display as "not pressed".
    • "false" is the default.
  • if set to "disabled", the button displays as disabled/no interaction possible.
    • no events are emitted when disabled
  • implicitly sets aria-pressed
  • a button does not switch it's state by itself
    • the user of the component has to set the state as reaction to an "action" event (eg. via toggle())

• use-config - for developers only.

  • Per default, the icon name identifies the (internal) config to be used. To keep the icon but style it alternatively, this attribute can specify the id of another config.
  • Note: Intended primarily to support button groups.
  • For a regular component user this is not relevant.

• label can be changed at runtime

• using a button as toggle for ewc-popover-sharing

  • There are recommendations regarding aria for this use case
  • ⚠️ Please see section "Aria recommendations" in the readme.md of ewc-popover-sharing

• The temporary state when mouse is being clicked but not yet released, is not considered

Details

For further details please see comment in cfg.js.

Usage

Installation

npm install @ewc-lib/ewc-icon-button

Import the component in your application:

// Using ES modules
import "@ewc-lib/ewc-css-common/custom-props.css";
import '@ewc-lib/ewc-icon-button';

Note about ewc-css-common

• "ewc-css-common/custom-props.css" is necessary for the correct styling of this component.
• It needs to be imported by the host project because it's not imported by this component implicitly.

Setting the size

This sets the dimensions of the button (not the icon):

ewc-icon-button::part(button) {
  width:48px;
  height:72px;
}

And this sets the dimensions of the icon and it's backdrop (circle):

<ewc-icon-button size="48">

• The icon always stays in the center
• Setting width/height of ewc-icon-button itself is not supported, please use sizing methods mentioned above.

Notes

Accessibility

The component is designed with accessibility in mind:

• Keyboard navigable element
• Sufficient color contrast

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

European Union Public License (EUPL)

Changelog

• 3.3.0-alpha

  • suppressTooltip feature
  • Note: Playwright tests are not adapted yet

• 3.2.0-alpha

  • tooltip pos configurable, default below

• 3.0.0-alpha

  • config and tests

• 2.5.0-alpha

  • tooltips

• 2.4.0-alpha

  • new style
  • new buttons

• 2.2.1-alpha

  • simplify config, increasing human readability, while retaining fine-granular config possibility
  • add mode for blue background
  • slight corrections of icon svg and colors

• 2.2.0-alpha

  • change config (colors) to match latest design
  • rename some files

• 2.1.0-alpha

  • correction of behaviour when toggling state "disabled"
  • style config for (support of) disabled linechart, barchart, dotplot, table
  • documentation

• 2.0.2-alpha

  • fix label casing bug

• 2.0.1-alpha

  • support integration, avoid unneccessary console output

• 2.0.0-alpha

  • update icons: linechart, barchart, hilo-chart (dotplot), table

• 1.1.0-alpha

  • add aria-disabled
  • rework posibilities sizing button and icon
  • docu

• 1.0.2-alpha

  • add width/height attribs
  • use peerDependencies
  • docu

• 1.0.1-alpha

  • add icons, implement state, add usage examples, config