OOUI/Widgets/Icons, Indicators, and Labels

Icon and indicator widgets contain small graphics (about the size of normal text) that efficiently convey information to help users interact with and understand an interface.

Labels are also used to help identify interface components. The value of a label can be set to a string, a label node, or a function that returns them.

Icons

The OOUI library contains over 100 icons that can be used by IconWidgets to create small graphical elements that handle events. IconWidgets should rarely be used without a label, though a label may be omitted if space is at a premium (e.g. in a toolbar) or if the icon is used in a context where its meaning is very clear to the user. In these cases, consider using a quiet ButtonWidget instead (which can include a label and icon itself).

To create an IconWidget, use an IconWidget with a LabelWidget (IconWidget & LabelWidget live demo):

// Create an IconWidget and label. Labels should be used unless space
// is at a premium or the meaning of the icon in its context is very clear.

// Create an icon and a label.
var removeIcon = new OO.ui.IconWidget( {
		icon: 'check',
		title: 'Check'
	} ),
	iconLabel = new OO.ui.LabelWidget( {
		label: 'Label the icon'
	} );
// Append the icon and label to the DOM.
$( document.body ).append( removeIcon.$element, iconLabel.$element );

IconWidgets support a number of methods that can be used to handle events and to get or set the value of contained elements. For example, getIcon() will return the name of the icon; setIcon(), which takes either a symbolic icon name or a map of icon names keyed by language, will set the icon; and setIconTitle() will set the icon title. For a full list of supported methods and configuration options, please see the code-level documentation for IconWidgets.

You need to load related styles somewhere before creating IconWidget, e.g. via ResourceLoader. Modules named by mask oojs-ui.styles.icons-*, e.g. oojs-ui.styles.icons-interactions for check icon. Group names can be found in demo page or in code.

Indicators

Indicators are small icons with very limited use cases:

• To act as indicating elements within widgets on limited screen space, for example to signify a 'clear' action in a SearchInputWidget.
• To clarify the function of a control that acts in an exceptional way (a dropdown that opens a menu instead of performing an action directly, for example).

IndicatorWidgets are often used by other widgets (e.g., text inputs, dropdowns, decorated options). In the following example, a TextInputWidget uses an indicator to help clarify that the field is required:

// Example: using an indicator to show the status of an element.
var textInput = new OO.ui.TextInputWidget( {
		placeholder: 'This field is required',
		indicator: 'required'
	} );
$( document.body ).append( textInput.$element );

The following indicators are included in the OOUI library:

Methods can be used to set or get the indicator title (setTitle() and getTitle(), respectively) or to get the name of the indicator (getIndicator()). For a full list of supported methods and configuration options, please see the code-level documentation for IndicatorWidgets.

Labels

Labels help identify the function of interface elements. Each LabelWidget can be configured with a label option that is set to a string, a label node, or a function:

• String: a plaintext string
• Label Node: a jQuery selection of elements. A jQuery selection is used for anything other than a plaintext label, e.g., a label that includes a link or special styling, such as a gray color or additional graphical elements.
• Function: a function that will produce a string in the future. Functions are used in cases where the label value is not currently defined. See Extending the Library for more information.

// Examples of LabelWidgets
// A plaintext label and a label with a jQuery selection of elements.
var label1 = new OO.ui.LabelWidget( {
		label: 'This is a plaintext label'
	} )
	label2 = new OO.ui.LabelWidget( {
		label: $( '<a href="default.html">This is a label with a link</a>'  )
	} );
$( document.body ).append( label1.$element, '<br>', label2.$element );

For a full list of supported methods and configuration options, please see the code-level documentation for LabelWidgets.