@element-public/react-icon-button v1.0.0
IconButton
Description
The icon button wraps the icon and provides button style interactions. Used when a user needs to interact with an icon.
See live demos on storybook
Install bundle from npm-e
npm i @element-public/react-components @element-public/themesOptional: install the component individually
npm i @element-public/react-icon-button @element-public/themesOpen ~/.npmrc in an editor and add the following line to enable the @element-public
scope:
@element-public:registry=https://npm.platforms.engineeringTroubleshooting
See below if you have never installed a package from Bayer's npm-enterprise or run into the following error:
npm ERR! code E401
npm ERR! Unable to authenticate, your authentication token seems to be invalid.
npm ERR! To correct this please trying logging in again with:
npm ERR! npm loginSetup an access token
See the
devtools npm-e guide
to learn how to create an access token if this is the first time you are using a
npm-e package at Bayer or you do not have a line that starts with the following
in your ~/.npmrc file:
//npm.platforms.engineering/:_authToken=
Notes
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:
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.
Icon Button Props
| 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. |
| badge | React.ReactNode | undefined | false | The custom icon button notification badge to be rendered. |
| 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. |
| dense | boolean | false | false | Enables a smaller IconButton. |
| disabled | boolean | false | false | Disables the icon button. |
| icon | string|React.ReactNode | null | false | For simple use-cases, this will automatically create the icon object. Does not work with toggle='true' |
| 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 |
| iconType | string | 'filled' | false | The icon type to be rendered. Not all icons have every type. To see which icons are available for different types see Material Icons docsAccepted Values: filled, outlined, rounded, two-tone, sharp |
| tabIndex | number | 0 | false | TabIndex of the button. |
| 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 idof 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-blackDeprecated Values: primary-alt, secondary-alt, primary, danger-alt, danger |
Icon Button Render Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
| 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. |
Icon Button Events
| 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. |
11 months ago