CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Interface

Button (ui/button)

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

interface
See source

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

Filtering

Properties

  • class : String

    observable

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

    See source

  • icon : String

    observable

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

    See source

  • isEnabled : Boolean

    observable

    Controls whether the button view is enabled, i.e. it can be clicked and execute an action.

    See source

    To change the "on" state of the button, use isOn instead.

    Defaults to true

  • isOn : Boolean

    observable

    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.

    See source

    To disable the button, use isEnabled instead.

    Defaults to true

  • isToggleable : Boolean

    observable

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

    See source

    Defaults to false

  • isVisible : Boolean

    observable

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

    See source

    Defaults to true

  • keystroke : Boolean

    observable

    (Optional) The keystroke associated with the button, i.e. CTRL+B, in the string format compatible with keyboard.

    See source

    Note: Use withKeystroke if you want to display the keystroke information next to the label.

  • label : String

    observable

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

    See source

  • labelStyle : String

    observable

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

    See source

  • tabindex : String

    observable

    (Optional) Controls the tabindex HTML attribute of the button. By default, the button is focusable but does not included in the Tab order.

    See source

    Defaults to -1

  • tooltip : Boolean | String | function

    observable

    (Optional) Tooltip of the button, i.e. displayed when hovering the button with the mouse cursor.

    See source

    • 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

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

    observable

    (Optional) The position of the tooltip. See position to learn more about the available position values.

    See source

    Note: It makes sense only when the tooltip attribute is defined.

    Defaults to 's'

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

    observable

    The HTML type of the button. Default button.

    See source

  • withKeystroke : Boolean

    observable

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

    See source

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

    Defaults to false

  • withText : Boolean

    observable

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

    See source

    Defaults to false

Events

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

    Fired when the class property changed value.

    See source

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (class).

    value : String

    New value of the class property with given key or null, if operation should remove property.

    oldValue : 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.

    See source

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (icon).

    value : String

    New value of the icon property with given key or null, if operation should remove property.

    oldValue : 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.

    See source

    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.

    See source

    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.

    See source

    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.

    See source

    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.

    See source

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (keystroke).

    value : Boolean

    New value of the keystroke property with given key or null, if operation should remove property.

    oldValue : Boolean

    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.

    See source

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (label).

    value : String

    New value of the label property with given key or null, if operation should remove property.

    oldValue : 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.

    See source

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (labelStyle).

    value : String

    New value of the labelStyle property with given key or null, if operation should remove property.

    oldValue : String

    Old value of the labelStyle 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.

    See source

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (tabindex).

    value : String

    New value of the tabindex property with given key or null, if operation should remove property.

    oldValue : String

    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.

    See source

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (tooltip).

    value : Boolean | String | function

    New value of the tooltip property with given key or null, if operation should remove property.

    oldValue : Boolean | String | function

    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.

    See source

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (tooltipPosition).

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

    New value of the tooltipPosition property with given key or null, if operation should remove property.

    oldValue : 's' | 'n' | 'e' | '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.

    See source

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (type).

    value : 'button' | 'submit' | 'reset' | 'menu'

    New value of the type property with given key or null, if operation should remove property.

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

    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.

    See source

    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.

    See source

    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.

    See source

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.