@ewc-lib/ewc-icon-button-group

EWC Icon-button group Component

Overview

The EWC Icon-button group component provides standardized radiobuttons for Eurostat web applications. It offers a consistent visual identity across Eurostat digital products while allowing for customization to meet specific application needs.

Features

• Responsive design that adapts to different screen sizes
• Customizable (there are 4 buttons available, arbitrary order)
• Button group respects tri-state of button (pressed/not pressed/disabled)
• Accessibility compliant

Screenshot

Description

The component shows a group of icon-buttons, displayed in "pill-"design and behaving like radio-buttons - i.e. only one button can be in "pressed" state at any time.

The ewc-icon-button-group HTML tag encloses ewc-icon-buttons. It modifies their style, handles events and implements the logic.

Note that adding/removing children at runtime is not supported.

Regarding focus, arrow keys work alongside the tab key.

Within a button-group, only buttons that are not currently pressed and not disabled can be focussed.

API

Properties and Attributes

Property	Attribute	Type	Default	Description
selectedIndex	selectedIndex	Number	0	The 0-based ordinal number of the button pressed.
selectedId	selectedId	Number	-	The id of the button pressed. Can be null if the id attribute is not set.
breakpoint	breakpoint	CSS String	650px	if viewport width is smaller than this, the buttons are displayed without label.
selectedElement		HTML element	-	The HTML element currently selected. Read only.

Notes:

• The attribute breakpoint does not support modification at runtime, all others do.
• The width of an ewc-icon-button (when used in conjunction with the ewc-icon-button-group) is determined as follows:
  • width of button-group < breakpoint: size or weight attribute of ewc-icon-button
  • width of button-group > breakpoint: 125px as per definition in the EWC standards

Enabling / Disabling

While selection is handled via attributes and properties, enabling/disabling is done with the following public member functions.

setEnabledById(id, isEnabled)
setEnabledByIndex(index, isEnabled)

• isEnabled is a boolean
• id is of type string
• index of type number

Caution

• ❗Refrain from setting state on a button directly when used in a group.
• This is because ewc-button-icon group is not aware of state changes it doesn't initiate itself.
• For the state "true" and "false", let ewc-button-icon handle this via selectedIndex or selectedId
• To disable a button, use setEnabledByIndex or setEnabledById
• Note that reading the state of a button is unproblematic - this note is just about setting the state.

Responsabilities

• Precaution has to be taken in case the button being disabled is the currently selected one.
  • The user of the component retains full control over what's happening in this case.
  • For instance, programmatically switching to another button before disabling a certain button.
    • And of course the effect such a button switch has in the host project / application.
• Disabling all buttons is technically supported.
  • But what that means in the context of the application is the user's responsability - the component can't know that.
  • In this case, the same applies - the user is responsible for setting a button when not all buttons are disabled anymore.

Example code for toggling between state "disabled" and "false"

const button = document.getElementById("myButton")
const group = document.getElementById("myButtonGroup")
group.setEnabledByIndex(0, button.state==="disabled")

❗ Don't miss to see also usage-examples/ directory for more examples, especially how to handle enable/disabling of a single button and also all buttons at once.

Events

• When a user attempts to press a button, a custom event named "action" is dispatched.
• The event detail contains the 0-based index of the button which was pressed.
  • It's the component user's responsability to actually set the button state to "pressed".
  • This is for two reasons:
    • provides possibility to prevent the button from being pressed
    • is consistent with the usage of the ewc-icon-button

Please see usage-examples/ directory which contains working source-code demonstrating how this works.

UML

Usage

Installation

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

Import the component in your application:

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

Note about ewc-css-common

• "ewc-css-common/custom-props.css" is necessary and downloaded along with this component.
• It needs to be imported by the host project because it's imported neither by ewc-icon-button nor ewc-icon-button-group.

Using in static HTML

Example:

<ewc-icon-button-group selectedIndex="1" breakpoint="1000px">
  <ewc-icon-button icon="linechart" use-config="grp-linechart" label="Line chart"></ewc-icon-button>
  <ewc-icon-button icon="barchart"  use-config="grp-barchart" label="Bar chart"></ewc-icon-button>
</ewc-icon-button-group>

To use a standard ewc-icon-button in the context of ewc-icon-button-group, use-config must be specified. For an explanation about the attribute use-config, please refer to the readme.md of ewc-icon-button.

Note: The usage-example/ directory contains a working example.

Migration guide

Updating to 3.0.0-alpha (from any older version)

Option to use ID instead of index

Referring to a button in a group can now be done via ID, additionally to the previously existing index.

ID in the event details

e.detail was only a number before (containing an ordinal index). Now it's an object w/ 2 fields: index and id.

document.getElementById("lightEnabled").addEventListener("action",(e)=>{
  console.log("button clicked or selected w/ kdb: ", e.detail.id, e.detail.index)
})

The ID is taken from the HTML tag's "id" attribute. If it's missing, e.detail.id is null.

Notes

Accessibility

The component is designed with accessibility in mind:

• Proper semantic HTML structure
• Keyboard navigable elements
• Sufficient color contrast
• Screen reader friendly with appropriate ARIA attributes

Browser Support

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

License

European Union Public License (EUPL)

Changelog

• 3.1.1-alpha

  • bugfix: id in action event contains id of previously selected element instead of currently clicked element

• 3.1.0-alpha

  • change config (colors) to match latest design

• 3.0.0-alpha

  • properly support disabled state,
  • add selection by id
  • add id-info to event
  • update usage examples
  • update documentation

• 2.0.3-alpha

  • fix label casing bug

• 2.0.2-alpha

  • support integration, update dependency, add aria-label

• 2.0.1-alpha

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

• 1.0.2-alpha

  • when pressed no checkmark displayed but keep the icon
  • introduce narrow width display
  • use peerDependencies
  • update docu

• 1.0.1-alpha

  • remove button label on narrow width
  • introduce attribute "breakpoint"