Button
Buttons are used to show users choices for actions and to arrange them in a clear hierarchy. They help users find the most important actions on a page or within a viewport and enable them to carry out these actions. The button label is used to clearly show users which action is triggered. Buttons allow users to confirm a change, complete steps in a task, or make decisions.
Construction
Code
<kol-button _label="Primary" _variant="primary"></kol-button>
<kol-button _label="Secondary" _variant="secondary"></kol-button>
<kol-button _label="Normal" _variant="normal"></kol-button>
<kol-button _label="Danger" _variant="danger"></kol-button>
<kol-button _label="Ghost" _variant="ghost"></kol-button>
Events
For the handling of events or callbacks, see
| Event | Value |
|---|---|
onClick | _value property |
onMouseDown | - |
Example
default
Disabled
Usage
Caption
To clearly label the button, use the _label attribute. _label="Button label"
Icons
Icons (_icons) can be specified either as a string or as an object. Pass the icon class as a string (e.g.: _icons="codicon codicon-home); the icon is displayed to the left of the text. The object is of type KoliBriAllIcon, so it can have one or more of the keys top, right, bottom and left. These are then either a string (see above) or an object of type KoliBriCustomIcon, which consists of icon (string, see above) and style (optional, style object).
Button without text
Using _hide-label the button will only show the icon (
_label auch dann gesetzt werden muss, wenn nur ein Icon angezeigt werden soll, dieses wird von Screenreadern vorgelesen und in den Tooltip gesetzt.Specify representation
To control the display, use the _variant attribute. The default value is primary, alternatively primary, secondary, normal, danger, ghost, or custom can also be set.
You can choose your own display by using the value custom. In this case, it is mandatory to set the _custom-class attribute so that the button can be selected in the shadow dome using CSS.
Best practices
- Use a primary button for the next best action. Remaining calls to action should be presented as a secondary button.
- Use buttons in consistent locations in the interface to improve user experience.
- Use only one primary button per viewport. A button style can appear any number of times throughout the page.
- The button label must describe the action the button performs. It should contain a verb (e.g. save). Use concise, specific, self-explanatory labels.
- Button labels should always include a noun when there is room for interpretation about what the verb is responsible for. Do not use generic terms such as "OK", especially in the event of an error. Mistakes are never “OK”.
- Do not use multiple buttons in the “primary” style within a grouping.
- Do not use buttons as a link or as a navigation element.
Accessibility
For people with a limited field of vision, positioning the icon in the button to the left of the label is optimal.
Problems with Disabled status
- Display contrasts
- Possibility of user feedback
Keyboard controls
| button | Function |
|---|---|
Tab | Jumps to the individual button and focuses on it. |
Enter | Executes the focused button's onClick method. |
Links and references
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
_accessKey | _access-key | Defines the key combination that can be used to trigger or focus the component's interactive element. | string | undefined | undefined |
_ariaControls | _aria-controls | Defines which elements are controlled by this component. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) | string | undefined | undefined |
_ariaDescription | _aria-description | Defines the value for the aria-description attribute. | string | undefined | undefined |
_ariaExpanded | _aria-expanded | Defines whether the interactive element of the component expanded something. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) | boolean | undefined | undefined |
_ariaSelected | _aria-selected | Defines whether the interactive element of the component is selected (e.g. role=tab). (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) | boolean | undefined | undefined |
_customClass | _custom-class | Defines the custom class attribute if _variant="custom" is set. | string | undefined | undefined |
_disabled | _disabled | Makes the element not focusable and ignore all events. | boolean | undefined | false |
_hideLabel | _hide-label | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | boolean | undefined | false |
_icons | _icons | Defines the icon classnames (e.g. _icons="fa-solid fa-user"). | KoliBriHorizontalIcons & KoliBriVerticalIcons | string | undefined | undefined |
_id | _id | [DEPRECATED] Will be removed in the next major version. Defines the internal ID of the primary component element. | string | undefined | undefined |
_inline | _inline | Defines whether the component is displayed as a standalone block or inline without enforcing a minimum size of 44px. | boolean | undefined | false |
_label (required) | _label | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to false to enable the expert slot. | string | undefined |
_name | _name | Defines the technical name of an input field. | string | undefined | undefined |
_on | -- | Defines the callback functions for button events. | undefined | { onClick?: EventValueOrEventCallback<MouseEvent, StencilUnknown> | undefined; onMouseDown?: EventCallback<MouseEvent> | undefined; } | undefined |
_role | _role | [DEPRECATED] We prefer the semantic role of the HTML element and do not allow for customization. We will remove this prop in the future. Defines the role of the components primary element. | "tab" | "treeitem" | undefined | undefined |
_shortKey | _short-key | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | string | undefined | undefined |
_tooltipAlign | _tooltip-align | Defines where to show the Tooltip preferably: top, right, bottom or left. | "bottom" | "left" | "right" | "top" | undefined | 'top' |
_type | _type | Defines either the type of the component or of the components interactive element. | "button" | "reset" | "submit" | undefined | 'button' |
_value | _value | Defines the value of the element. | boolean | null | number | object | string | undefined | undefined |
_variant | _variant | Defines which variant should be used for presentation. | "custom" | "danger" | "ghost" | "normal" | "primary" | "secondary" | "tertiary" | undefined | 'normal' |
Methods
getValue
getValue() => Promise<StencilUnknown>
Returns the current value.
Returns
Type: Promise<StencilUnknown>
kolFocus() => Promise<void>
Sets focus on the internal element.
Returns
Type: Promise<void>