OOjs UI/Widgets/Buttons and Switches

OOjs UI
Introduction
About the libraryOOjs UI/About the library OOjs primerOOjs UI/OOjs primer
Getting started
Creating interfaces programmatically PHP examplesOOjs UI/PHP examples Using OOjs UI in MediaWikiOOjs UI/Using OOjs UI in MediaWiki
Working with widgets
ElementsOOjs UI/Elements GroupElementsOOjs UI/Elements/Groups FlaggedElementsOOjs UI/Elements/Flagged LookupElementsOOjs UI/Elements/Lookup WidgetsOOjs UI/Widgets Icons, Indicators, and Labels Buttons and SwitchesOOjs UI/Widgets/Buttons and Switches Selects and OptionsOOjs UI/Widgets/Selects and Options InputsOOjs UI/Widgets/Inputs PopupsOOjs UI/Widgets/Popups Progress barsOOjs UI/Widgets/Progress bars LayoutsOOjs UI/Layouts Fields and FieldsetsOOjs UI/Layouts/Fields and Fieldsets FormsOOjs UI/Layouts/Forms Stacks and PanelsOOjs UI/Layouts/Stacks and Panels MenusOOjs UI/Layouts/Menu Layout Booklets and PagesOOjs UI/Layouts/Booklets and Pages Index and TabPanelsOOjs_UI/Index_and_TabPanels WindowsOOjs UI/Windows Simple messagesOOjs UI/Windows/Simple messages DialogsOOjs UI/Windows/Dialogs Process DialogsOOjs UI/Windows/Process Dialogs Message DialogsOOjs UI/Windows/Message Dialogs Window managersOOjs UI/Windows/Window managers ToolbarsOOjs UI/Toolbars Other conceptsOOjs UI/Concepts
See also
Fixing scripts and gadgetsOOjs UI/Fixing scripts and gadgets
v · d · e

Button widgets are created with button classes. You can create a wide variety of looks, feels, and functionality via class configuration options.

The basic button class is the ButtonWidget class. Specialized button classes include:

ButtonInputWidget class for HTML form buttons
ToggleSwitchWidget and ToggleButtonWidget classes for toggle switches, which have either on or off states
PopupButtonWidget class for popup buttons

By default, a rendered button is a link that has no href attribute.

1 Buttons
2 Toggle buttons
3 Popup buttons
4 Toggle switches

Buttons[edit]

To create a basic button use the ButtonWidget class:

// Example: A ButtonWidget configured with an icon, label, and styling flag.
// Create a new ButtonWidget. 
var button = new OO.ui.ButtonWidget();

// Configure the ButtonWidget. In this example, methods are used to configure the
// button's icon, label, and styling flag. 
button.setIcon( 'info' )
.setLabel( 'Button with icon' )
.setFlags( 'progressive' );
 
// Append the button to the DOM.  
$( 'body' ).append( button.$element );

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:

// Assign a hyperlink to open when the button is clicked, as well as a target 
// window in which to open the link, using the 'href' and 'target' 
// options, respectively. The hyperlink and href can also be set using the 
// setTarget() and setHref() methods.
var buttonOpen = new OO.ui.ButtonWidget( {
  label: 'Click Me!',
  href: 'http://www.mediawiki.org',
  target: '_blank'
} );    
$( 'body' ).append( buttonOpen.$element );

Add a label with the label option:

// Set the 'label' option to plain text, a jQuery selection of elements, 
// or a function. 
var buttonWithLabel = new OO.ui.ButtonWidget( { 
  label: 'Button Label'
} );
$( 'body' ).append( buttonWithLabel.$element );

Use styling flags to customize the look and feel:

// Use styling flags to customize the look and feel of a button widget. 
// Flags include: constructive, destructive, and progressive. 
// Constructive styling is applied to convey that the widget will create something. 
var buttonC = new OO.ui.ButtonWidget( {
  label: 'Constructive',
  flags:'constructive'
} );
 
// Destructive styling is applied to convey that the widget will remove something. 
var buttonD = new OO.ui.ButtonWidget( {
  label: 'Destructive',
  flags:'destructive'
} );
 
// Progressive styling is applied to convey that the widget will move the user 
// forward in whatever process they are in.
var buttonP = new OO.ui.ButtonWidget( {
    label: 'Progressive',
    flags:'progressive'
} );
$( 'body' ).append( buttonC.$element, buttonD.$element, buttonP.$element );

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

// A button can be framed (the default) or frameless. 
// Set the 'framed' option to 'false' to remove the border. 
var buttonNF = new OO.ui.ButtonWidget( {
  label: 'Frameless Constructive Button',
  flags: 'constructive',
  framed: false
} );    
$( 'body' ).append( buttonNF.$element );

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

// Assign a button title with the 'title' option.
var buttonWithTitle = new OO.ui.ButtonWidget( {
  label: 'Button with Title',
  title: 'I am a button'
} );
$( 'body' ).append( buttonWithTitle.$element );

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

// To disable a button, set the 'disabled' option to 'true'. 
var buttonDisabled = new OO.ui.ButtonWidget( {
  label: 'Disabled Constructive Button',
  flags: 'constructive',
  disabled: true
} ); 
$( 'body' ).append( buttonDisabled.$element );

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

// Assign an icon and icon title with the 'icon' and 'iconTitle' 
// options, respectively. 
var buttonIcon = new OO.ui.ButtonWidget( {
  label: 'Button with Icon',
  icon: 'remove',
  iconTitle: 'Remove'
} );    
$( 'body' ).append( buttonIcon.$element );

Add an indicator with the indicator option:

// Assign an indicator with the 'indicator' option. 
// Indicators include: down, next, previous, required, up, alert.
var buttonIndicator = new OO.ui.ButtonWidget( {
  label: 'Button with Indicator',
  indicator: 'down'
} );
$( 'body' ).append( buttonIndicator.$element );

Add additional CSS styling with the classes option:

 <style>
.my-button .oo-ui-buttonElement-button {
  color: purple;
}
.my-button-pretty {
  border: solid 1px pink;
}
</style>
<script>
// Assign additional CSS styles to a button widget with the 'classes' option.
// Note that CSS styles are added to the top level (e.g., the outermost div) 
// of the element. To style a nested element, such as a link, specify the 
// relevant class name (e.g., .oo-ui-buttonElement-button, in the above CSS) 
// in the style sheet. 
var buttonClassy = new OO.ui.ButtonWidget( {
  label: 'Pretty, pretty',
  classes: [ 'my-button',  'my-button-pretty' ]
} );    
$( 'body' ).append( buttonClassy.$element ); 
</script>

Specify a tab order with the tabIndex option:

// Specify a tab order with the 'tabIndex' option. 
var button1 = new OO.ui.ButtonWidget( {
  label: 'fourth', 
  tabIndex: 4
} );
var button2 = new OO.ui.ButtonWidget( { 
  label: 'second',
  tabIndex: 2
} );
var button3 = new OO.ui.ButtonWidget( {
  label: 'third',
  tabIndex: 3
} );
var button4 = new OO.ui.ButtonWidget( { 
  label: 'first',  
  tabIndex: 1
} );   
$( 'body' ).append( button1.$element, button2.$element, button3.$element, button4.$element );

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

// Use the 'accessKey' option to assign a keyboard shortcut to a button widget. 
var buttonWithKey = new OO.ui.ButtonWidget( { 
  label: 'My keyboard shortcut is: m', 
  href:'http://www.mediawiki.org',
  accessKey: 'm'
} );
$( 'body' ).append( buttonWithKey.$element );

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[edit]

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:

// Toggle buttons in the 'off' and 'on' state. By default, the button
// is in the 'off' state.
var toggleButton1 = new OO.ui.ToggleButtonWidget( {
  label: 'Toggle Button off'
} );
var toggleButton2 = new OO.ui.ToggleButtonWidget( {
  label: 'Toggle Button on',
  value: true
} );
// Append the buttons to the DOM.
$( 'body' ).append( toggleButton1.$element, toggleButton2.$element );

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:

// In this example, the setValue() method is 
// used to change the button's state to 'on'.
var toggleButton = new OO.ui.ToggleButtonWidget( {
  label: 'Toggle Button'
} );
// Change the button state to 'on'.
toggleButton.setValue( true );
 
$( 'body' ).append( toggleButton.$element );
 
// The getValue() method returns the state of the button:
console.log( 'The button is:', toggleButton.getValue() );

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

Popup buttons[edit]

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#Overlays for details.

To create a popup button use the PopupButtonWidget class:

// Create a popup button. The 'popup' config contains the 
// configurations that will be passed to the popup.
var popupButton = new OO.ui.PopupButtonWidget( { 
  label: 'Popup button with options', 
  icon: 'menu', 
  popup: {
    $content: $( '<p>Additional options here.</p>' ),
    padded: true,
    align: 'forwards'
  }
} );
// Append the button to the DOM.
$( 'body' ).append( popupButton.$element );

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:

// This example illustrates creating a popup button and then using getPopup() 
// to get it. The getLabel() method gets the popup label ('This is the popup'),
//  which is written to the console log.
var popupButton = new OO.ui.PopupButtonWidget( { 
  label: 'Popup button', 
  icon : 'menu', 
  popup : {
    $content: $( '<p>Add additional content or options here.</p>' ),
    label: 'This is the popup',
    padded: true,
    align: 'forwards'
  }
} );
 
// Append the button to the DOM.
$( 'body' ).append( popupButton.$element );
 
 // getPopup()
 console.log( 'The popup label:', popupButton.getPopup().getLabel() );

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

Toggle switches[edit]

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:

// This example shows toggle switches in the off and on position. 
 
// Note that the example uses a FieldsetLayout to format the toggle switches
// and to add labels to identify each ('On' and 'Off'). For more information 
// about fieldset layouts, please see the Layout section.
 
// Create the toggle switches.
var toggleSwitch1 = new OO.ui.ToggleSwitchWidget( { 
  value: false 
} );
var toggleSwitch2 = new OO.ui.ToggleSwitchWidget( { 
  value: true
} );
 
// Create a Fieldset layout.
var fieldset = new OO.ui.FieldsetLayout( { 
  label: 'Toggle switches' 
} );
 
// Add the toggle switches to FieldLayouts, which are added to the FieldsetLayout 
// using the addItems() method.
fieldset.addItems( [ 
    new OO.ui.FieldLayout( toggleSwitch1, { label: 'Off', align: 'top' } ),
    new OO.ui.FieldLayout( toggleSwitch2, { label: 'On', align: 'top' } )
] );
$( 'body' ).append( fieldset.$element );

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.