Button
Button widget, wraps and styles a regular <button> element. Can display text and icon and also
allows specifying button color. Supports different appearances, by setting rendition
to one of:
- 'text' - Flat appearance with text only, no background or border
- 'outlined' - Transparent button with border
- 'tonal' - Flat appearance with "soft" background color
- 'filled' - Flat appearance with stronger background color
- 'elevated' - Raised appearance
//<code-header>
fiddle.title = 'Button renditions';
//</code-header>
targetElement.style.gridTemplateColumns = 'auto auto auto auto';
const
onClick = () => Toast.show('Button clicked'),
renditions = ['text', 'outlined', 'tonal', 'filled', 'elevated'];
for (const rendition of renditions) {
new Button({
appendTo : targetElement,
text : StringHelper.capitalize(rendition),
width : '9em',
rendition,
onClick
});
new Button({
appendTo : targetElement,
icon : 'fa-flask',
text : StringHelper.capitalize(rendition),
width : '9em',
rendition,
onClick
});
new Button({
appendTo : targetElement,
icon : 'fa-cog',
rendition,
onClick
});
new Button({
appendTo : targetElement,
icon : 'fa-times',
disabled : true,
rendition,
onClick
});
}// Green button with text and icon
const button = new Button({
appendTo : document.body,
icon : 'fa-plus-circle',
text : 'Add',
color : 'b-green',
onClick : () => {}
});
Button with menu
Buttons can also have a menu that is shown on click, or on click or hover of only the menu icon part of the button (if split is set):
//<code-header>
fiddle.title = 'Button with menu';
//</code-header>
const renditions = ['text', 'outlined', 'tonal', 'filled', 'elevated'];
for (const rendition of renditions) {
new Button({
appendTo : targetElement,
icon : 'fa-chart-line',
rendition,
menu : [
{ icon : 'fa fa-chart-pie', text : 'Item 1', onItem : () => console.log('Item 1 activated') },
{ icon : 'fa fa-chart-bar', text : 'Item 2', onItem : () => console.log('Item 2 activated') }
]
});
new Button({
rendition,
text : 'Settings button',
icon : 'fa-cog',
appendTo : targetElement,
menu : {
// Other menu configs can be passed here
items : [
{ icon : 'fa fa-hammer', text : 'Item 1', onItem : () => console.log('Item 1 activated') },
{ icon : 'fa fa-wrench', text : 'Item 2', onItem : () => console.log('Item 2 activated') }
]
}
});
new Button({
rendition,
text : 'Settings button',
icon : 'fa-cog',
appendTo : targetElement,
split : 'hover',
menu : {
// Other menu configs can be passed here
items : [
{ icon : 'fa fa-hammer', text : 'Item 1', onItem : () => console.log('Item 1 activated') },
{ icon : 'fa fa-wrench', text : 'Item 2', onItem : () => console.log('Item 2 activated') }
]
}
});
}const button = new Button({
appendTo : document.body,
icon : 'fa-chart',
menu : {
items : [
{
text : 'Click me',
onItem : () => console.log('I was clicked')
}
]
}
});
Click handling in a complex widget
In the case of a button which is part of a complex UI within a larger Bryntum widget, use
of the string form for handlers is advised. A handler which starts with 'up.' will
be resolved by looking in owning widgets of the Button. For example a Calendar may
have handlers for its buttons configured in:
new Calendar({
appendTo : document.body,
project : myProjectConfig,
sidebar : {
items : {
addNew : {
weight : 0,
text : 'New',
// The Button's ownership will be traversed to find this function name.
// It will be called on the outermost Calendar widget.
onClick : 'up.onAddNewClick'
}
}
},
// Button handler found here
onAddNewClick() {
// Use Calendar API which creates event in the currently active date
this.createEvent();
}
});
This class may be operated by the keyboard. Space presses the button and invokes any
click handler, and ArrowDown activates any configured menu.
Configs
92
Configs
92Common
Other
The button behavioral type, will be applied as a type attribute to this button's element.
If provided, turns the button into a link.
Button icon class, a developer-defined CSS class string which results in the desired icon.
Note that demos use Font Awesome icons, but no icons are actually built in.
This may also be configured as the URL of an image (Detected by searching for a / in the string).
Button icon alignment. May be 'start' or 'end'. Defaults to 'start'
Initially pressed or not. Only applies with toggleable = true.
const toggleButton = new Button({
toggleable : true,
text : 'Enable cool action'
});
A CSS class to add to the pressed state of the button. A b-pressed CSS class is always added,
when a button is pressed.
Icon class for the buttons pressed state, a developer-defined CSS class string which results in the desired icon. Only applies to toggle buttons
Note that demos use Font Awesome icons, but no icons are actually built in.
new Button({
// Icon for unpressed button
icon : 'fa-wine-glass',
// Icon for pressed button
pressedIcon : 'fa-wine-glass-alt',
// Only applies to toggle buttons
toggleable : true
});
Predefined style to use for the button. Possible values are:
'elevated'- Raised button with box-shadow'filled'- Filled with the primary color'tonal'- Filled with a faded shade of the primary color'outlined'- Outlined with borders and pale or transparent fill'text'- Transparent text-only button
The supplied value will be part of the button's class list, as b-button-{rendition}.
If no value is provided, a default rendition will be determined based on the theme.
Set to true to create a split button. A split button has a main action and a dropdown arrow to show a menu.
The menu only shows when the arrow is clicked, not when the main button is clicked.
Set to 'mouseover' to show the menu when hovering the arrow part of the button
as well as when toggling by clicking it.
Set to 'hover' to show the menu only when hovering the arrow part of the button -
the menu will hide when the mouse leaves the icon to outside of the icon or menu.
The button will only toggle its pressed state and action its click handler when the main
part of the button is clicked.
Set to true to perform action on clicking the button if it's already pressed
and belongs to a toggleGroup.
The tab index of the button, or null for natural tab order (recommended). Setting to 0 is equivalent
to natural tab order, but is unnecessary for buttons since they are naturally tabbable (i.e., accessible
via the TAB key). Setting to -1 disables tabbability but allows for focus to be set to the element
programmatically.
From MDN documentation:
Warning: You are recommended to only use 0 and -1 as tabindex values. Avoid using tabindex values
greater than 0 and CSS properties that can change the order of focusable HTML elements (Ordering flex
items).
Doing so makes it difficult for people who rely on using keyboard for navigation or assistive technology
to navigate and operate page content. Instead, write the document with the elements in a logical sequence.
The target attribute for the href config
The button's text. You can also supply a DomConfig or an array of DomConfigs for complex button content.
Enabled toggling of the button (stays pressed when pressed).
Indicates that this button is part of a group where only one button can be pressed. Assigning a value
also sets toggleable to true.
When part of a ButtonGroup, you can set toggleGroup on it as an alternative to on each button. This config can then be used to override that value if needed.
const yesButton = new Button({
toggleGroup : 'yesno',
text : 'Yes'
});
const noButton = new Button({
toggleGroup : 'yesno',
text : 'No'
});
DOM
Float & align
Layout
Misc
Scrolling
Properties
83
Properties
83Class hierarchy
Other
The button behavioral type, will be applied as a type attribute to this button's element.
If provided, turns the button into a link.
Button icon class, a developer-defined CSS class string which results in the desired icon.
Note that demos use Font Awesome icons, but no icons are actually built in.
This may also be configured as the URL of an image (Detected by searching for a / in the string).
Button icon alignment. May be 'start' or 'end'. Defaults to 'start'
Initially pressed or not. Only applies with toggleable = true.
const toggleButton = new Button({
toggleable : true,
text : 'Enable cool action'
});
A CSS class to add to the pressed state of the button. A b-pressed CSS class is always added,
when a button is pressed.
Icon class for the buttons pressed state, a developer-defined CSS class string which results in the desired icon. Only applies to toggle buttons
Note that demos use Font Awesome icons, but no icons are actually built in.
new Button({
// Icon for unpressed button
icon : 'fa-wine-glass',
// Icon for pressed button
pressedIcon : 'fa-wine-glass-alt',
// Only applies to toggle buttons
toggleable : true
});
Predefined style to use for the button. Possible values are:
'elevated'- Raised button with box-shadow'filled'- Filled with the primary color'tonal'- Filled with a faded shade of the primary color'outlined'- Outlined with borders and pale or transparent fill'text'- Transparent text-only button
The supplied value will be part of the button's class list, as b-button-{rendition}.
If no value is provided, a default rendition will be determined based on the theme.
Set to true to create a split button. A split button has a main action and a dropdown arrow to show a menu.
The menu only shows when the arrow is clicked, not when the main button is clicked.
Set to 'mouseover' to show the menu when hovering the arrow part of the button
as well as when toggling by clicking it.
Set to 'hover' to show the menu only when hovering the arrow part of the button -
the menu will hide when the mouse leaves the icon to outside of the icon or menu.
The button will only toggle its pressed state and action its click handler when the main
part of the button is clicked.
The tab index of the button, or null for natural tab order (recommended). Setting to 0 is equivalent
to natural tab order, but is unnecessary for buttons since they are naturally tabbable (i.e., accessible
via the TAB key). Setting to -1 disables tabbability but allows for focus to be set to the element
programmatically.
From MDN documentation:
Warning: You are recommended to only use 0 and -1 as tabindex values. Avoid using tabindex values
greater than 0 and CSS properties that can change the order of focusable HTML elements (Ordering flex
items).
Doing so makes it difficult for people who rely on using keyboard for navigation or assistive technology
to navigate and operate page content. Instead, write the document with the elements in a logical sequence.
The target attribute for the href config
The button's text. You can also supply a DomConfig or an array of DomConfigs for complex button content.
Enabled toggling of the button (stays pressed when pressed).
Indicates that this button is part of a group where only one button can be pressed. Assigning a value
also sets toggleable to true.
When part of a ButtonGroup, you can set toggleGroup on it as an alternative to on each button. This config can then be used to override that value if needed.
const yesButton = new Button({
toggleGroup : 'yesno',
text : 'Yes'
});
const noButton = new Button({
toggleGroup : 'yesno',
text : 'No'
});
CSS
DOM
Layout
Misc
Functions
59
Functions
59Other
Iterate over all widgets owned by this widget and any descendants.
Note: Due to this method aborting when the function returns false, beware of using short form arrow
functions. If the expression executed evaluates to false, iteration will terminate.
Due to the menu config being a lazy config and only being converted to be a
Menu instance just before it's shown, the menu will not be part of the iteration before
it has been shown once.
| Parameter | Type | Description |
|---|---|---|
fn | function | A function to execute upon all descendant widgets.
Iteration terminates if this function returns |
deep | Boolean | Pass as |
Returns true if iteration was not aborted by a step returning false
Toggle button state (only use with toggleable = true)
| Parameter | Type | Description |
|---|---|---|
pressed | Boolean | Specify to force a certain toggle state |
Configuration
Events
Misc
Events
19
Events
19Fires when the default action is performed (the button is clicked)
// Adding a listener using the "on" method
button.on('action', ({ source, event, domEvent }) => {
});| Parameter | Type | Description |
|---|---|---|
source | Button | The button |
event | Event | DEPRECATED - Use domEvent instead. |
domEvent | Event | The triggering DOM event.
Using the |
This event is triggered when the button's menu is about to be shown.
// Adding a listener using the "on" method
button.on('beforeShowMenu', ({ source, menu, userAction, domEvent }) => {
});| Parameter | Type | Description |
|---|---|---|
source | Button | This Button instance. |
menu | Menu | This button's menu instance. |
userAction | Boolean |
|
domEvent | Event | The original DOM event that triggered the action, if any.
Using the |
Fires before the button is toggled (the pressed state is changed). If the button is part of
a toggleGroup and you need to process the pressed button only, consider using
click event or action event.
Return false to prevent the toggle to the new pressed state.
// Adding a listener using the "on" method
button.on('beforeToggle', ({ source, pressed, userAction, domEvent }) => {
});| Parameter | Type | Description |
|---|---|---|
source | Button | Toggled button |
pressed | Boolean | New pressed state |
userAction | Boolean |
|
domEvent | Event | The original DOM event that triggered the action, if any.
Using the |
Fires when the button is clicked
// Adding a listener using the "on" method
button.on('click', ({ source, event, domEvent }) => {
});| Parameter | Type | Description |
|---|---|---|
source | Button | The button |
event | Event | DEPRECATED - Use domEvent instead. |
domEvent | Event | The triggering DOM event.
Using the |
Fires when the button is toggled via a UI interaction (the pressed state is changed). If the button is part of a toggleGroup and you need to process the pressed button only, consider using click event or action event.
// Adding a listener using the "on" method
button.on('toggle', ({ source, pressed, userAction, domEvent }) => {
});| Parameter | Type | Description |
|---|---|---|
source | Button | Toggled button |
pressed | Boolean | New pressed state |
userAction | Boolean |
|
domEvent | Event | The original DOM event that triggered the action, if any.
Using the |
Event handlers
19
Event handlers
19Called when the default action is performed (the button is clicked)
new Button({
onAction({ source, event, domEvent }) {
}
});| Parameter | Type | Description |
|---|---|---|
source | Button | The button |
event | Event | DEPRECATED - Use domEvent instead. |
domEvent | Event | The triggering DOM event.
Using the |
This event is called when the button's menu is about to be shown.
new Button({
onBeforeShowMenu({ source, menu, userAction, domEvent }) {
}
});| Parameter | Type | Description |
|---|---|---|
source | Button | This Button instance. |
menu | Menu | This button's menu instance. |
userAction | Boolean |
|
domEvent | Event | The original DOM event that triggered the action, if any.
Using the |
Called before the button is toggled (the pressed state is changed). If the button is part of
a toggleGroup and you need to process the pressed button only, consider using
click event or action event.
Return false to prevent the toggle to the new pressed state.
new Button({
onBeforeToggle({ source, pressed, userAction, domEvent }) {
}
});| Parameter | Type | Description |
|---|---|---|
source | Button | Toggled button |
pressed | Boolean | New pressed state |
userAction | Boolean |
|
domEvent | Event | The original DOM event that triggered the action, if any.
Using the |
Called when the button is clicked
new Button({
onClick({ source, event, domEvent }) {
}
});| Parameter | Type | Description |
|---|---|---|
source | Button | The button |
event | Event | DEPRECATED - Use domEvent instead. |
domEvent | Event | The triggering DOM event.
Using the |
Called when the button is toggled via a UI interaction (the pressed state is changed). If the button is part of a toggleGroup and you need to process the pressed button only, consider using click event or action event.
new Button({
onToggle({ source, pressed, userAction, domEvent }) {
}
});| Parameter | Type | Description |
|---|---|---|
source | Button | Toggled button |
pressed | Boolean | New pressed state |
userAction | Boolean |
|
domEvent | Event | The original DOM event that triggered the action, if any.
Using the |
Typedefs
6
Typedefs
6CSS variables
100
CSS variables
100| Name | Description |
|---|---|
--b-button-box-shadow | Button box-shadow, overridden by renditions |
--b-button-text-align | Button text-align |
--b-button-icon-only-border-radius | Border-radius for icon-only buttons |
--b-button-font-weight | Button text font-weight |
--b-button-gap | Gap between icon and label |
--b-button-height | Button height |
--b-button-icon-padding-inline | Inline padding for buttons with icon |
--b-button-end-icon-padding-inline | Inline padding for buttons with icon at the end |
--b-button-menu-padding-inline | Inline padding for buttons with menu |
--b-button-opacity | Button opacity |
--b-button-padding-inline | Text-only button inline padding |
--b-button-border-radius | Button border-radius |
--b-button-elevated-box-shadow | ElevatedBox-shadow for elevated buttons |
--b-button-elevated-color | ElevatedText color for elevated buttons |
--b-button-filled-color | FilledText color for filled buttons |
--b-button-tonal-border-width | TonalBorder width for tonal buttons |
--b-button-outlined-border-width | OutlinedBorder width for outlined buttons |
--b-button-outlined-border-color | OutlinedBorder color for outlined buttons |
--b-button-outlined-background | OutlinedBackground for outlined buttons |
--b-button-type-text-background | TextBackground for text buttons |
--b-button-elevated-background | ElevatedBackground for elevated buttons |
--b-button-filled-background | FilledBackground for filled buttons |
--b-button-outlined-hover-border-color | OutlinedBorder color for hovered outlined buttons |
--b-button-outlined-color | OutlinedText color for outlined buttons |
--b-button-tonal-background | TonalBackground for tonal buttons |
--b-button-tonal-color | TonalText color for tonal buttons |
--b-button-tonal-border-color | TonalBorder color for tonal buttons |
--b-button-type-text-color | TextText color for text buttons |
| Active | |
--b-button-active-box-shadow | Box-shadow for active buttons, overridden by renditions |
--b-button-elevated-active-box-shadow | ElevatedBox-shadow for active elevated buttons |
--b-button-elevated-active-background | ElevatedBackground for active elevated buttons |
--b-button-filled-active-background | FilledBackground for active filled buttons |
--b-button-outlined-active-background | OutlinedBackground for active outlined buttons |
--b-button-tonal-active-background | TonalBackground for active tonal buttons |
--b-button-type-text-active-background | TextBackground for active text buttons |
| Disabled | |
--b-button-disabled-opacity | Opacity for disabled buttons |
--b-button-disabled-border-color | Border-color for disabled buttons |
--b-button-outlined-disabled-background | OutlinedBackground for disabled outlined buttons |
--b-button-outlined-disabled-border-color | OutlinedBorder color for disabled outlined buttons |
--b-button-type-text-disabled-background | TextBackground for disabled text buttons |
--b-button-disabled-background | Background for disabled buttons |
--b-button-disabled-color | Disabled button text color |
| Focused | |
--b-button-focus-outline-width | Focus outline width |
--b-button-focus-outline-offset | Focus outline offset |
--b-button-focus-box-shadow | Box-shadow for focused buttons, overridden by renditions |
--b-button-focus-border-color | Border-color for focused buttons, overridden by renditions |
--b-button-elevated-focus-box-shadow | ElevatedBox-shadow for focused elevated buttons |
--b-button-outlined-focus-border-color | OutlinedBorder color for focused outlined buttons |
--b-button-type-text-focused-background | Background for focused text buttons |
--b-button-focus-outline-color | Focus outline color |
--b-button-elevated-focused-background | ElevatedBackground for focused elevated buttons |
--b-button-filled-focused-background | FilledBackground for focused filled buttons |
--b-button-outlined-focused-background | OutlinedBackground for focused outlined buttons |
--b-button-tonal-focused-background | TonalBackground for focused tonal buttons |
| Hovered | |
--b-button-hover-box-shadow | Box-shadow for hovered buttons, overridden by renditions |
--b-button-elevated-hover-box-shadow | ElevatedBox-shadow for hovered elevated buttons |
--b-button-filled-hover-box-shadow | FilledBox-shadow for hovered filled buttons |
--b-button-tonal-hover-box-shadow | TonalBox-shadow for hovered tonal buttons |
--b-button-elevated-hover-background | ElevatedBackground for hovered elevated buttons |
--b-button-filled-hover-background | FilledBackground for hovered filled buttons |
--b-button-outlined-hover-background | OutlinedBackground for hovered outlined buttons |
--b-button-tonal-hover-background | TonalBackground for hovered tonal buttons |
--b-button-type-text-hover-background | TextBackground for hovered text buttons |
| Pressed | |
--b-button-pressed-box-shadow | Box-shadow for pressed buttons, overridden by renditions |
--b-button-outlined-pressed-color | OutlinedText color for pressed outlined buttons |
--b-button-elevated-pressed-background | ElevatedBackground for pressed elevated buttons |
--b-button-elevated-pressed-hover-background | ElevatedBackground for hovered pressed elevated buttons |
--b-button-filled-pressed-background | FilledBackground for pressed filled buttons |
--b-button-filled-pressed-hover-background | FilledBackground for hovered pressed filled buttons |
--b-button-outlined-pressed-background | OutlinedBackground for pressed outlined buttons |
--b-button-outlined-pressed-hover-background | OutlinedBackground for hovered pressed outlined buttons |
--b-button-tonal-pressed-background | TonalBackground for pressed tonal buttons |
--b-button-tonal-pressed-hover-background | TonalBackground for hovered pressed tonal buttons |
--b-button-type-text-pressed-background | TextBackground for pressed text buttons |
--b-button-type-text-pressed-hover-background | TextBackground for hovered pressed text buttons |