Icon Button component for Element React
The icon button wraps the icon and provides button style interactions. Used when a user needs to interact with an icon.
- Verify that you have access to (https://docs.int.bayer.com/cloud/devops/artifactory/)[Bayer Artifactory]
- Verify your token is correctly set up in your .npmrc as per the link above
- Verify you have the @element scope configured in your .npmrc
- @element:registry=https://artifactory.bayer.com/artifactory/api/npm/npm-platforms-engineering/
- Install the component and themes bundles
- npm i @element/react-components @element/themes
- alternatively install the component individually along with the themes bundle npm i @element/react-icon-button @element/themes
The Icon Button makes an Icon clickable, so a user can interact with it.
Many options exist for Icon Button use, like with Icon. First, there is an extensive list of premade and labeled Icons. This list is included under the 'Icon Search' story, under the Icon tab, on Storybook, and is based on the Google Material list, which can be found at the following link:
- https://fonts.google.com/icons?selected=Material+Icons
Similarly to Icon, Icon Button offers use cases with Notification Badges, with and without a counter. Examples of these behaviors are shown under their respective Storybook stories.
The Toggleable story demonstrates an Icon Button that shows whether or not it has been clicked. In this example, the star Icon Button is filled in when clicked, and only outlined when it is unclicked. This behavior could be useful for showing an on/off function.
| Name | Type | Default | Required | Description |
| ----------------------- | ------------------------------------------ | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| active | boolean | false | false | Programmatically sets the toggle state of the button when used as a toggle button. If not set, the toggle state will be managed internally. |
| ariaLabel | string | null | false | Accessibility label for assistive technologies. |
| ariaLabelledBy | string | null | false | Id of an element serving as a label for this IconButton instance. Used by assistive technologies. |
| badgePlacement | string | 'right-start' | false | The placement of the notification badge on the icon to start. It will flip to the opposite side if there is no room.
Accepted Values: right-start, left-start |
| className | string | undefined | false | The css class name to be passed through to the component markup. |
| disabled | boolean | false | false | Disables the icon button. |
| emphasis | string | 'high' | false | For filled variants, choose between the two emphasis levels for icon Button to improve visual hierarchy and user interface clarity
Accepted Values: high, low |
| icon | string\|React.ReactNode | null | false | For simple use-cases, this will automatically create the icon object. Does not work with toggle='true' |
| iconProps | object | undefined | false | Pass props to the internal Icon instance. Ignored if you pass your own object. |
| iconSize | string | 'medium' | false | One of 'xsmall', 'small', 'medium', 'large', and 'xlarge' will change the size of the icon. Defaults to medium.
Accepted Values: xsmall, small, medium, large, xlarge |
| iconSource | string | 'material-icons' | false | Choose between the classic Material Icons (default), newer Material Symbols, or custom.
Accepted Values: material-icons, material-symbols |
| iconType | string | 'filled' | false | The material icon type/style to be use. NOTE: Not all icons have every type and material-symbols only support outlined, rounded, and sharp. To see which icons are available for different types see Material Icons docs
Accepted Values: filled, outlined, rounded, two-tone, sharp |
| noHover | boolean | false | false | Disables the hover effect. |
| tabIndex | number | 0 | false | TabIndex of the button. |
| tag | string\|React.ElementType\|React.Component | null | false | By default a button will be rendered, this allows another tag/component to be used instead. A block type element/component is suggested. |
| toggleOffAriaLabel | string | null | false | The aria-label value to be read by a screen-reader when the button is toggled off. Example 'Add to Favorites'. Alternatively, toggleOffAriaLabelledBy may be used instead. |
| toggleOffAriaLabelledBy | string | null | false | The aria-labelledbyvalue when the button is toggled on. This should be the id of a parent element to be read by a screen reader instead of aria-label. |
| toggleOnAriaLabel | string | null | false | The aria-label value to be read by a screen-reader when the button is toggled on. Example 'Remove from Favorites'. Alternatively, toggleOnAriaLabelledBy may be used instead. |
| toggleOnAriaLabelledBy | string | null | false | The aria-labelledbyvalue when the button is toggled on. This should be the id of a parent element to be read by a screen reader instead of aria-label. |
| variant | string | empty string | false | Variants prefixed with filled- will add a background color to the icon according to the theme. Variants prefixed with color- will change the color of the icon according to the theme.
Accepted Values: filled-danger-alt, filled-danger, filled-primary, filled-secondary, color-primary, color-secondary, color-on-dark, color-on-unknown-black, secondary-on-surface
Deprecated Values: primary-alt, secondary-alt, primary, danger-alt, danger |
| Name | Type | Default | Required | Deprecated | Description |
| ----- | ------- | --------- | -------- | ----------------------------- | ----------------------------- |
| dense | boolean | undefined | false | Use iconSize='small' instead. | Enables a smaller IconButton. |
| Name | Type | Default | Required | Description |
| --------- | --------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| badge | React.ReactNode | undefined | false | The custom icon button notification badge to be rendered. |
| children | React.ReactNode | null | false | The content when when using the IconButton normally. Expects an Icon component. For toggle button functionality, use toggleOn and toggleOff instead. |
| toggleOff | React.ReactNode | null | false | The content to be rendered when the IconButton is toggled off. Expects an Icon component. The typical use case for a toggle button would be to set an Icon for toggleOn and toggleOff, leaving children blank. |
| toggleOn | React.ReactNode | null | false | The content to be rendered when the IconButton is toggled on. Expects an Icon component. The typical use case for a toggle button would be to set an Icon for toggleOn and toggleOff, leaving children blank. |
| Name | Default | Required | Params | Description |
| ------- | --------- | -------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| onClick | undefined | false | 1. Name: event, Type: event, Description: The DOM JavaScript event. | Fired when the user clicks the IconButton, will return toggle state, if applicable. |