Button (ui/button)
@ckeditor/ckeditor5-ui/src/button/button
The button interface. Implemented by, among others, ButtonView
,
SplitButtonView
and
DropdownButtonView
.
Filtering
Properties
-
(Optional) The ARIA property reflected by the
aria-checked
DOM attribute used by assistive technologies. -
(Optional) The ARIA property reflected by the
aria-label
DOM attribute used by assistive technologies. -
(Optional) The ARIA property reflected by the
aria-ariaLabelledBy
DOM attribute used by assistive technologies. -
(Optional) The additional CSS class set on the button.
-
(Optional) An XML content of the icon. When defined, an
iconView
should be added to the button. -
Controls whether the button view is enabled, i.e. it can be clicked and execute an action.
To change the "on" state of the button, use
isOn
instead.Defaults to
true
-
Controls whether the button view is "on". It makes sense when a feature it represents is currently active, e.g. a bold button is "on" when the selection is in the bold text.
To disable the button, use
isEnabled
instead.Defaults to
true
-
Controls whether the button view is a toggle button (two–state) for assistive technologies.
Defaults to
false
-
Controls whether the button view is visible. Visible by default, buttons are hidden using a CSS class.
Defaults to
true
-
(Optional) The keystroke associated with the button, i.e. CTRL+B, in the string format compatible with
keyboard
.Note: Use
withKeystroke
if you want to display the keystroke information next to the label. -
(Optional) The value of the
style
attribute of the label. -
(Optional) The property reflected by the
role
DOM attribute to be used by assistive technologies. -
(Optional) Controls the
tabindex
HTML attribute of the button. By default, the button is focusable but does not included in the Tab order.Defaults to
-1
-
tooltip : string | boolean | ( string, undefined | string ) => string
module:ui/button/button~Button#tooltip
(Optional) Tooltip of the button, i.e. displayed when hovering the button with the mouse cursor.
- If defined as a
Boolean
(e.g.true
), then combination oflabel
andkeystroke
will be set as a tooltip. - If defined as a
String
, tooltip will equal the exact text of thatString
. - If defined as a
Function
,label
andkeystroke
will be passed to that function, which is to return a string with the tooltip text.
const view = new ButtonView( locale ); view.tooltip = ( label, keystroke ) => `A tooltip for ${ label } and ${ keystroke }.`
Defaults to
false
- If defined as a
-
(Optional) The position of the tooltip. See
TooltipManager
to learn more about the tooltip system.Note: It makes sense only when the
tooltip
attribute is defined.Defaults to
's'
-
-
(Optional) Controls whether the label of the button is hidden (e.g. an icon–only button).
Defaults to
false
Events
-
change:ariaChecked( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:ariaChecked
Fired when the
ariaChecked
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
ariaChecked
).value : boolean
New value of the
ariaChecked
property with given key ornull
, if operation should remove property.oldValue : boolean
Old value of the
ariaChecked
property with given key ornull
, if property was not set before.
-
change:ariaLabel( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:ariaLabel
Fired when the
ariaLabel
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
ariaLabel
).value : string
New value of the
ariaLabel
property with given key ornull
, if operation should remove property.oldValue : string
Old value of the
ariaLabel
property with given key ornull
, if property was not set before.
-
change:ariaLabelledBy( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:ariaLabelledBy
Fired when the
ariaLabelledBy
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
ariaLabelledBy
).value : string
New value of the
ariaLabelledBy
property with given key ornull
, if operation should remove property.oldValue : string
Old value of the
ariaLabelledBy
property with given key ornull
, if property was not set before.
-
change:class( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:class
Fired when the
class
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
class
).value : undefined | string
New value of the
class
property with given key ornull
, if operation should remove property.oldValue : undefined | string
Old value of the
class
property with given key ornull
, if property was not set before.
-
change:icon( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:icon
Fired when the
icon
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
icon
).value : undefined | string
New value of the
icon
property with given key ornull
, if operation should remove property.oldValue : undefined | string
Old value of the
icon
property with given key ornull
, if property was not set before.
-
change:isEnabled( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:isEnabled
Fired when the
isEnabled
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
isEnabled
).value : boolean
New value of the
isEnabled
property with given key ornull
, if operation should remove property.oldValue : boolean
Old value of the
isEnabled
property with given key ornull
, if property was not set before.
-
change:isOn( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:isOn
Fired when the
isOn
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
isOn
).value : boolean
New value of the
isOn
property with given key ornull
, if operation should remove property.oldValue : boolean
Old value of the
isOn
property with given key ornull
, if property was not set before.
-
change:isToggleable( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:isToggleable
Fired when the
isToggleable
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
isToggleable
).value : boolean
New value of the
isToggleable
property with given key ornull
, if operation should remove property.oldValue : boolean
Old value of the
isToggleable
property with given key ornull
, if property was not set before.
-
change:isVisible( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:isVisible
Fired when the
isVisible
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
isVisible
).value : boolean
New value of the
isVisible
property with given key ornull
, if operation should remove property.oldValue : boolean
Old value of the
isVisible
property with given key ornull
, if property was not set before.
-
change:keystroke( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:keystroke
Fired when the
keystroke
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
keystroke
).value : undefined | string
New value of the
keystroke
property with given key ornull
, if operation should remove property.oldValue : undefined | string
Old value of the
keystroke
property with given key ornull
, if property was not set before.
-
change:label( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:label
Fired when the
label
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
label
).value : undefined | string
New value of the
label
property with given key ornull
, if operation should remove property.oldValue : undefined | string
Old value of the
label
property with given key ornull
, if property was not set before.
-
change:labelStyle( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:labelStyle
Fired when the
labelStyle
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
labelStyle
).value : undefined | string
New value of the
labelStyle
property with given key ornull
, if operation should remove property.oldValue : undefined | string
Old value of the
labelStyle
property with given key ornull
, if property was not set before.
-
change:role( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:role
Fired when the
role
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
role
).value : string
New value of the
role
property with given key ornull
, if operation should remove property.oldValue : string
Old value of the
role
property with given key ornull
, if property was not set before.
-
change:tabindex( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:tabindex
Fired when the
tabindex
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
tabindex
).value : number
New value of the
tabindex
property with given key ornull
, if operation should remove property.oldValue : number
Old value of the
tabindex
property with given key ornull
, if property was not set before.
-
change:tooltip( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:tooltip
Fired when the
tooltip
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
tooltip
).value : string | boolean | ( string, undefined | string ) => string
New value of the
tooltip
property with given key ornull
, if operation should remove property.oldValue : string | boolean | ( string, undefined | string ) => string
Old value of the
tooltip
property with given key ornull
, if property was not set before.
-
change:tooltipPosition( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:tooltipPosition
Fired when the
tooltipPosition
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
tooltipPosition
).value : 'e' | 's' | 'n' | 'w' | 'sw' | 'se'
New value of the
tooltipPosition
property with given key ornull
, if operation should remove property.oldValue : 'e' | 's' | 'n' | 'w' | 'sw' | 'se'
Old value of the
tooltipPosition
property with given key ornull
, if property was not set before.
-
change:type( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:type
Fired when the
type
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
type
).value : 'button' | 'menu' | 'reset' | 'submit'
New value of the
type
property with given key ornull
, if operation should remove property.oldValue : 'button' | 'menu' | 'reset' | 'submit'
Old value of the
type
property with given key ornull
, if property was not set before.
-
change:withKeystroke( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:withKeystroke
Fired when the
withKeystroke
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
withKeystroke
).value : boolean
New value of the
withKeystroke
property with given key ornull
, if operation should remove property.oldValue : boolean
Old value of the
withKeystroke
property with given key ornull
, if property was not set before.
-
change:withText( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:change:withText
Fired when the
withText
property changed value.Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
withText
).value : boolean
New value of the
withText
property with given key ornull
, if operation should remove property.oldValue : boolean
Old value of the
withText
property with given key ornull
, if property was not set before.
-
execute( eventInfo )
module:ui/button/button~Button#event:execute
-
set:ariaChecked( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:ariaChecked
Fired when the
ariaChecked
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
ariaChecked
).value : boolean
New value of the
ariaChecked
property with given key ornull
, if operation should remove property.oldValue : boolean
Old value of the
ariaChecked
property with given key ornull
, if property was not set before.
-
set:ariaLabel( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:ariaLabel
Fired when the
ariaLabel
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
ariaLabel
).value : string
New value of the
ariaLabel
property with given key ornull
, if operation should remove property.oldValue : string
Old value of the
ariaLabel
property with given key ornull
, if property was not set before.
-
set:ariaLabelledBy( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:ariaLabelledBy
Fired when the
ariaLabelledBy
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
ariaLabelledBy
).value : string
New value of the
ariaLabelledBy
property with given key ornull
, if operation should remove property.oldValue : string
Old value of the
ariaLabelledBy
property with given key ornull
, if property was not set before.
-
set:class( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:class
Fired when the
class
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
class
).value : undefined | string
New value of the
class
property with given key ornull
, if operation should remove property.oldValue : undefined | string
Old value of the
class
property with given key ornull
, if property was not set before.
-
set:icon( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:icon
Fired when the
icon
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
icon
).value : undefined | string
New value of the
icon
property with given key ornull
, if operation should remove property.oldValue : undefined | string
Old value of the
icon
property with given key ornull
, if property was not set before.
-
set:isEnabled( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:isEnabled
Fired when the
isEnabled
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
isEnabled
).value : boolean
New value of the
isEnabled
property with given key ornull
, if operation should remove property.oldValue : boolean
Old value of the
isEnabled
property with given key ornull
, if property was not set before.
-
set:isOn( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:isOn
Fired when the
isOn
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
isOn
).value : boolean
New value of the
isOn
property with given key ornull
, if operation should remove property.oldValue : boolean
Old value of the
isOn
property with given key ornull
, if property was not set before.
-
set:isToggleable( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:isToggleable
Fired when the
isToggleable
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
isToggleable
).value : boolean
New value of the
isToggleable
property with given key ornull
, if operation should remove property.oldValue : boolean
Old value of the
isToggleable
property with given key ornull
, if property was not set before.
-
set:isVisible( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:isVisible
Fired when the
isVisible
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
isVisible
).value : boolean
New value of the
isVisible
property with given key ornull
, if operation should remove property.oldValue : boolean
Old value of the
isVisible
property with given key ornull
, if property was not set before.
-
set:keystroke( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:keystroke
Fired when the
keystroke
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
keystroke
).value : undefined | string
New value of the
keystroke
property with given key ornull
, if operation should remove property.oldValue : undefined | string
Old value of the
keystroke
property with given key ornull
, if property was not set before.
-
set:label( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:label
Fired when the
label
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
label
).value : undefined | string
New value of the
label
property with given key ornull
, if operation should remove property.oldValue : undefined | string
Old value of the
label
property with given key ornull
, if property was not set before.
-
set:labelStyle( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:labelStyle
Fired when the
labelStyle
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
labelStyle
).value : undefined | string
New value of the
labelStyle
property with given key ornull
, if operation should remove property.oldValue : undefined | string
Old value of the
labelStyle
property with given key ornull
, if property was not set before.
-
set:role( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:role
Fired when the
role
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
role
).value : string
New value of the
role
property with given key ornull
, if operation should remove property.oldValue : string
Old value of the
role
property with given key ornull
, if property was not set before.
-
set:tabindex( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:tabindex
Fired when the
tabindex
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
tabindex
).value : number
New value of the
tabindex
property with given key ornull
, if operation should remove property.oldValue : number
Old value of the
tabindex
property with given key ornull
, if property was not set before.
-
set:tooltip( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:tooltip
Fired when the
tooltip
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
tooltip
).value : string | boolean | ( string, undefined | string ) => string
New value of the
tooltip
property with given key ornull
, if operation should remove property.oldValue : string | boolean | ( string, undefined | string ) => string
Old value of the
tooltip
property with given key ornull
, if property was not set before.
-
set:tooltipPosition( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:tooltipPosition
Fired when the
tooltipPosition
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
tooltipPosition
).value : 'e' | 's' | 'n' | 'w' | 'sw' | 'se'
New value of the
tooltipPosition
property with given key ornull
, if operation should remove property.oldValue : 'e' | 's' | 'n' | 'w' | 'sw' | 'se'
Old value of the
tooltipPosition
property with given key ornull
, if property was not set before.
-
set:type( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:type
Fired when the
type
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
type
).value : 'button' | 'menu' | 'reset' | 'submit'
New value of the
type
property with given key ornull
, if operation should remove property.oldValue : 'button' | 'menu' | 'reset' | 'submit'
Old value of the
type
property with given key ornull
, if property was not set before.
-
set:withKeystroke( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:withKeystroke
Fired when the
withKeystroke
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
withKeystroke
).value : boolean
New value of the
withKeystroke
property with given key ornull
, if operation should remove property.oldValue : boolean
Old value of the
withKeystroke
property with given key ornull
, if property was not set before.
-
set:withText( eventInfo, name, value, oldValue )
module:ui/button/button~Button#event:set:withText
Fired when the
withText
property is going to be set but is not set yet (before thechange
event is fired).Parameters
eventInfo : EventInfo
An object containing information about the fired event.
name : string
Name of the changed property (
withText
).value : boolean
New value of the
withText
property with given key ornull
, if operation should remove property.oldValue : boolean
Old value of the
withText
property with given key ornull
, if property was not set before.
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.