Interface

Button (ui/button)

@ckeditor/ckeditor5-ui/src/button/button

interface

The button interface. Implemented by, among others, ButtonView, SplitButtonView and DropdownButtonView.

Filtering

Properties

  • observable

    ariaLabel : string | undefined

    (Optional) The ARIA property reflected by the aria-label DOM attribute used by assistive technologies.

  • observable

    ariaLabelledBy : string | undefined

    (Optional) The ARIA property reflected by the aria-ariaLabelledBy DOM attribute used by assistive technologies.

  • observable

    class : undefined | string

    (Optional) The additional CSS class set on the button.

  • observable

    icon : undefined | string

    (Optional) An XML content of the icon. When defined, an iconView should be added to the button.

    The user must provide the entire XML string, not just the path. See the UI library guide for details.

  • observable

    isEnabled : boolean

    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

  • observable

    isOn : boolean

    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

  • observable

    isToggleable : boolean

    Controls whether the button view is a toggle button (two–state) for assistive technologies.

    Defaults to false

  • observable

    isVisible : boolean

    Controls whether the button view is visible. Visible by default, buttons are hidden using a CSS class.

    Defaults to true

  • observable

    keystroke : undefined | string

    (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.

  • observable

    label : undefined | string

    The label of the button view visible to the user when withText is true. It can also be used to create a tooltip.

  • observable

    labelStyle : undefined | string

    (Optional) The value of the style attribute of the label.

  • observable

    role : string | undefined

    (Optional) The property reflected by the role DOM attribute to be used by assistive technologies.

  • observable

    tabindex : number

    (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

  • observable

    tooltip : string | boolean | ( string, undefined | string ) => string

    (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 of label and keystroke will be set as a tooltip.
    • If defined as a String, tooltip will equal the exact text of that String.
    • If defined as a Function, label and keystroke 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

  • observable

    tooltipPosition : 'e' | 's' | 'n' | 'w' | 'sw' | 'se'

    (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'

  • observable

    type : 'button' | 'menu' | 'reset' | 'submit'

    The HTML type of the button.

    Defaults to 'button'

  • observable

    withKeystroke : boolean

    (Optional) Controls whether the keystroke of the button is displayed next to its label.

    Note: This property requires a keystroke to be defined in the first place.

    Defaults to false

  • observable

    withText : boolean

    (Optional) Controls whether the label of the button is hidden (e.g. an icon–only button).

    Defaults to false

Events

  • change:ariaLabel( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : string

    Old value of the ariaLabel property with given key or null, if property was not set before.

  • change:ariaLabelledBy( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : string

    Old value of the ariaLabelledBy property with given key or null, if property was not set before.

  • change:class( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : undefined | string

    Old value of the class property with given key or null, if property was not set before.

  • change:icon( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : undefined | string

    Old value of the icon property with given key or null, if property was not set before.

  • change:isEnabled( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : boolean

    Old value of the isEnabled property with given key or null, if property was not set before.

  • change:isOn( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : boolean

    Old value of the isOn property with given key or null, if property was not set before.

  • change:isToggleable( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : boolean

    Old value of the isToggleable property with given key or null, if property was not set before.

  • change:isVisible( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : boolean

    Old value of the isVisible property with given key or null, if property was not set before.

  • change:keystroke( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : undefined | string

    Old value of the keystroke property with given key or null, if property was not set before.

  • change:label( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : undefined | string

    Old value of the label property with given key or null, if property was not set before.

  • change:labelStyle( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : undefined | string

    Old value of the labelStyle property with given key or null, if property was not set before.

  • change:role( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : string

    Old value of the role property with given key or null, if property was not set before.

  • change:tabindex( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : number

    Old value of the tabindex property with given key or null, if property was not set before.

  • change:tooltip( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : string | boolean | ( string, undefined | string ) => string

    Old value of the tooltip property with given key or null, if property was not set before.

  • change:tooltipPosition( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : 'e' | 's' | 'n' | 'w' | 'sw' | 'se'

    Old value of the tooltipPosition property with given key or null, if property was not set before.

  • change:type( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : 'button' | 'menu' | 'reset' | 'submit'

    Old value of the type property with given key or null, if property was not set before.

  • change:withKeystroke( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : boolean

    Old value of the withKeystroke property with given key or null, if property was not set before.

  • change:withText( eventInfo, name, value, oldValue )

    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 or null, if operation should remove property.

    oldValue : boolean

    Old value of the withText property with given key or null, if property was not set before.

  • execute( eventInfo )

    Fired when the button view is clicked. It won't be fired when the button isEnabled is false.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

  • set:ariaLabel( eventInfo, name, value, oldValue )

    Fired when the ariaLabel property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : string

    Old value of the ariaLabel property with given key or null, if property was not set before.

  • set:ariaLabelledBy( eventInfo, name, value, oldValue )

    Fired when the ariaLabelledBy property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : string

    Old value of the ariaLabelledBy property with given key or null, if property was not set before.

  • set:class( eventInfo, name, value, oldValue )

    Fired when the class property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : undefined | string

    Old value of the class property with given key or null, if property was not set before.

  • set:icon( eventInfo, name, value, oldValue )

    Fired when the icon property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : undefined | string

    Old value of the icon property with given key or null, if property was not set before.

  • set:isEnabled( eventInfo, name, value, oldValue )

    Fired when the isEnabled property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : boolean

    Old value of the isEnabled property with given key or null, if property was not set before.

  • set:isOn( eventInfo, name, value, oldValue )

    Fired when the isOn property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : boolean

    Old value of the isOn property with given key or null, if property was not set before.

  • set:isToggleable( eventInfo, name, value, oldValue )

    Fired when the isToggleable property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : boolean

    Old value of the isToggleable property with given key or null, if property was not set before.

  • set:isVisible( eventInfo, name, value, oldValue )

    Fired when the isVisible property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : boolean

    Old value of the isVisible property with given key or null, if property was not set before.

  • set:keystroke( eventInfo, name, value, oldValue )

    Fired when the keystroke property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : undefined | string

    Old value of the keystroke property with given key or null, if property was not set before.

  • set:label( eventInfo, name, value, oldValue )

    Fired when the label property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : undefined | string

    Old value of the label property with given key or null, if property was not set before.

  • set:labelStyle( eventInfo, name, value, oldValue )

    Fired when the labelStyle property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : undefined | string

    Old value of the labelStyle property with given key or null, if property was not set before.

  • set:role( eventInfo, name, value, oldValue )

    Fired when the role property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : string

    Old value of the role property with given key or null, if property was not set before.

  • set:tabindex( eventInfo, name, value, oldValue )

    Fired when the tabindex property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : number

    Old value of the tabindex property with given key or null, if property was not set before.

  • set:tooltip( eventInfo, name, value, oldValue )

    Fired when the tooltip property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : string | boolean | ( string, undefined | string ) => string

    Old value of the tooltip property with given key or null, if property was not set before.

  • set:tooltipPosition( eventInfo, name, value, oldValue )

    Fired when the tooltipPosition property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : 'e' | 's' | 'n' | 'w' | 'sw' | 'se'

    Old value of the tooltipPosition property with given key or null, if property was not set before.

  • set:type( eventInfo, name, value, oldValue )

    Fired when the type property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : 'button' | 'menu' | 'reset' | 'submit'

    Old value of the type property with given key or null, if property was not set before.

  • set:withKeystroke( eventInfo, name, value, oldValue )

    Fired when the withKeystroke property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : boolean

    Old value of the withKeystroke property with given key or null, if property was not set before.

  • set:withText( eventInfo, name, value, oldValue )

    Fired when the withText property is going to be set but is not set yet (before the change 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 or null, if operation should remove property.

    oldValue : boolean

    Old value of the withText property with given key or null, if property was not set before.