## Overview
npm install @ewc-lib/ewc-icon-button-groupThe 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.
- 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
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.
| 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
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
- ❗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.
- 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"
``javascript`
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.
- 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.
`bash`
npm install @ewc-lib/ewc-icon-button-group
Import the component in your application:
`javascript`
// Using ES modules
import "@ewc-lib/ewc-css-common/custom-props.css"
import '@ewc-lib/ewc-icon-button-group';
- "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.
Example:
`html`
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.
Referring to a button in a group can now be done via ID, additionally to the previously existing index.
e.detail was only a number before (containing an ordinal index). Now it's an object w/ 2 fields: index and id.
`javascript``
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.
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
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
European Union Public License (EUPL)
- 3.2.0-alpha
- latest design
- 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"