OOUI/Widgets/Buttons and Switches

Button widgets are generally created with the ButtonWidget class, and a wide variety of looks, feels, and functionality can be customized via configuration options and methods. By default, a rendered button is link that has no ‘href’. HTML form buttons should use the ButtonInputWidget class.

Toggle switches, which have either an ‘on’ or ‘off’ state, are created with the ToggleSwitchWidget class. The library also contains a ToggleButtonWidget that has this same behavior.

Popup buttons, created with the PopupButtonWidget class, are also available.

Buttons
To create a basic button use the ButtonWidget class:

Configuration settings can be passed to the widget in the form of a configuration object or set using the widget’s methods. The examples below use a configuration object, but the settings could just have easily been specified with methods.

Assign a hyperlink to open and a target with href and target:'''

Add a label with the label option:

Use styling flags to customize the look and feel:

To remove a button frame (create a frameless button), set the framed option to 'false':

Assign a button title (displayed when the user hovers the mouse pointer over it) with the title option:

To disable a button, set the disabled option to 'true':

Add an icon and icon title with the icon and iconTitle options, respectively:

Add an indicator with the indicator option:

Add additional CSS styling with the classes option:

Specify a tab order with the tabIndex option:

Use the accessKey option to assign a keyboard shortcut to a button widget:

ButtonWidgets define the following public methods: setHref, setTarget, getHref, getTarget, but many additional methods are inherited or mixed in from other classes. For a full list of supported methods and configuration options, please see the code-level documentation.

Toggle buttons
Toggle buttons are buttons that have a state (‘on’ or ‘off’) which is represented by a Boolean value. The state of the button can be gotten with the getValue method which will return ‘true’ if the button is ‘on’ and ‘false’ otherwise (the default). ‘Change’ events contain the value of the toggle button’s  state, which allows applications to easily respond to the events asynchronously.

To create a toggle button use the ToggleButtonWidget class:



Like basic buttons, toggle buttons can be configured with icons, indicators, titles, styling flags, and labels. In addition to the methods supported by basic buttons, the class supports a getValue and setValue method, which are used to get and set the value of the button, respectively:

For a complete list of supported methods and configuration options, please see the code-level documentation for the ToggleButtonWidget class.

Popup buttons
Popup buttons toggle the visibility of a contained PopupWidget, which is used to display additional information or options. The popup itself can be accessed using the getPopup method.

The popup can be placed inside an overlay to avoid being clipped by outer elements. See OOjs UI/Concepts for details.

To create a popup button use the PopupButtonWidget class:

Popup buttons can be configured in the same ways that basic buttons can be. Use the getPopup method to return the popup so that can be interacted with: For a complete list of supported methods and configuration options, please see the code-level documentation for the PopupButtonWidget class.

Toggle switches
Like toggle buttons, toggle switches have an on/off state, which is represent by a Boolean value (‘true’ for ‘on’, and ‘false’ otherwise, the default). The ‘off’ state is represented visually by a slider in the leftmost position. Toggle switches do not have a label config option.

To create a toggle-switch button use the ToggleSwitchWidget class:

ToggleSwitchWidgets can be disabled or configured with additional CSS classes. Each also has a state value (‘false’ by default), which can be set via a config option or the setValue method. The getValue method will get the state value. For a complete list of supported methods and configuration options, please see the code-level documentation.