OOUI/Widgets/Buttons and Switches

OOUI
Introduction
About the library OOjs primer
Getting started
Creating interfaces programmatically PHP examples Using OOUI in MediaWiki
Working with widgets
Elements GroupElements FlaggedElements LookupElements DraggableElements Widgets Icons, Indicators, and Labels Buttons and Switches Selects and Options Inputs Popups Progress bars Layouts Fields and Fieldsets Forms Stacks and Panels Menus Booklets and Pages Index and TabPanels Windows Simple messages Dialogs Process Dialogs Message Dialogs Window managers Toolbars Themes Other concepts
See also
Fixing scripts and gadgets


v · d · e

Button widgets are created with button classes. You can create a 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 element <a> that has no href attribute.

Buttons

[edit]

To create a basic button use the ButtonWidget class with the label option (live demo):

// Set the 'label' option to plain text, a jQuery selection of elements, 
// or a function. 
var buttonWithLabel = new OO.ui.ButtonWidget( { 
	label: 'Button Label'
} );
$( document.body ).append( buttonWithLabel.$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 buttonHome = new OO.ui.ButtonWidget( {
	label: 'Click Me!',
	href: 'https://www.mediawiki.org',
	target: '_blank'
} );    
$( document.body ).append( buttonHome.$element );

Use styling flags to customize the look and feel (live demo):

// Use styling flags to customize the look and feel of a button widget. 
// Flags include: progressive and destructive. 

// Progressive styling is applied to convey that the widget will move the user 
// forward in or finish whatever process they are in.
var buttonP = new OO.ui.ButtonWidget( {
	label: 'Progressive',
	flags: 'progressive'
} );

// Destructive styling is applied to convey that the widget will remove something. 
var buttonD = new OO.ui.ButtonWidget( {
	label: 'Destructive',
	flags: 'destructive'
} );

$( document.body ).append( buttonP.$element, buttonD.$element );

Add an icon to the play (live demo):

// 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( 'lightbulb' )
      .setLabel( 'Button with icon' )
      .setFlags( 'progressive' );
 
// Append the button to the DOM.  
$( document.body ).append( button.$element );

To see what icons are available, refer to the icon demo page.

Use a quiet button (also known as frameless button) by setting the framed option to false (live demo):

// A button can be framed (the default norm) or quiet (frameless). 
// Set the 'framed' option to 'false' to remove the border in normal state. 
var buttonQuiet = new OO.ui.ButtonWidget( {
	label: 'Quiet Progressive Button',
	flags: 'progressive',
	framed: false
} );    
$( document.body ).append( buttonQuiet.$element );

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

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

Disable a button by setting the disabled option to true (live demo):

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

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

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

If you use an icon-only button, you should add a hidden label for screen reader users by adding label and invisibleLabel: true options or a title.

Add an indicator with the indicator option (live demo):

// 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'
} );
$( document.body ).append( buttonIndicator.$element );

Add additional CSS styling with the classes option:

<style>
.my-button .oo-ui-buttonElement-button {
	color: rebeccapurple;
}

.my-button-pretty {
	border-color: 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, weirdly',
	classes: [ 'my-button',  'my-button-pretty' ]
} );    
$( document.body ).append( buttonClassy.$element ); 
</script>

Specify a tab order with the tabIndex option. Please be aware that changing the tab order might negatively impact users of assistive technology if not done carefully:

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

Use the accessKey option to assign a keyboard shortcut to a button widget. Please be aware that using accessKey might negatively impact screen readers:

// Use the 'accessKey' option to assign a keyboard shortcut to a ButtonWidget. 
var buttonWithKey = new OO.ui.ButtonWidget( { 
		label: 'Keyboard access key: G', 
		href: 'https://www.mediawiki.org',
		accessKey: 'g'
	} );
$( document.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 (live demo):

// Toggle button in the 'on' state. By default, the button
// is in the 'off' state.
var toggleButton = new OO.ui.ToggleButtonWidget( {
	label: 'Toggle button on',
	value: true
} );
// Append the button to the DOM.
$( document.body ).append( toggleButton.$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 );
 
$( document.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 OOUI/Concepts#Overlays for details.

To create a popup button use the PopupButtonWidget class (live demo):

// 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.
$( document.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.
$( document.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 (live demo):

// 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: true
	} ),
	toggleSwitch2 = new OO.ui.ToggleSwitchWidget( { 
		value: false 
	} ),
	toggleSwitch3 = new OO.ui.ToggleSwitchWidget( { 
		disabled: true,
		value: true
	} );

// Create a Fieldsetlayout.
var fieldset = new OO.ui.FieldsetLayout( { 
		label: '' 
	} );
 
// Add the toggle switches to FieldLayouts, which are added to the FieldsetLayout 
// using the addItems() method.
fieldset.addItems( [ 
	new OO.ui.FieldLayout( toggleSwitch1, { 
		label: 'On (checked)', 
		align: 'top' 
	} ),
	new OO.ui.FieldLayout( toggleSwitch2, { 
		label: 'Off', 
		align: 'top' 
	} ),
	new OO.ui.FieldLayout( toggleSwitch3, { 
		label: 'Disabled (checked)', 
		align: 'top' 
	} )
] );
$( document.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.

OOUI is maintained by the Design System Team.

Get help:

#wikimedia-editing ^connect ← Live chat (IRC)
wikitech-l ← Mailing list
Talk:OOUI ← Talk page
ooui (add task) ← Phabricator project page