OOUI/Widgets/Icons, Indicators, and Labels

From MediaWiki.org
< OOUI‎ | Widgets
Jump to: navigation, search

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

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 frameless ButtonWidget instead (which can include a label and icon itself).

To create an IconWidget, use an IconWidget with a LabelWidget:

Example of an IconWidget

// 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.
var removeIcon = new OO.ui.IconWidget( {
  icon: 'remove',
  iconTitle: 'Remove'
} );
// Create a label.
var iconLabel = new OO.ui.LabelWidget( {
  label: 'Remove the items'
} );
// Append the icon and label to the DOM
$( '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.

Indicators[edit]

Indicators are small graphics that are generally used in two ways:

  • To draw attention to the status of an item. For example, an indicator might be used to show that an item in a list has errors that need to be resolved.
  • To clarify the function of a control that acts in an exceptional way (a button that opens a menu instead of performing an action directly, for example).

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

Example of an Indicator

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

The following indicators are included in the OOUI library:

WidgetsIndicators.png

Methods can be used to set or get the indicator title (setIndicatorTitle() and getIndicatorTitle(), 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[edit]

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.

Example of a LabelWidget

// Examples of LabelWidgets

// A plaintext label.
var label1 = new OO.ui.LabelWidget( {
  label: 'This is a plaintext label'
} );
// A label with a jQuery selection of elements
var label2 = new OO.ui.LabelWidget( {
  label: $( '<a href="default.html">This is a label with a link</a>'  )
} );
$( '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.