← 4.11.2 The summary elementTable of contents4.11.4 The menu element →

4.11.3 The command element

Categories:
Metadata content.
Flow content.
Phrasing content.
Contexts in which this element can be used:
Where metadata content is expected.
Where phrasing content is expected.
Content model:
Empty.
Content attributes:
Global attributes
type
label
icon
disabled
checked
radiogroup
command
Also, the title attribute has special semantics on this element.
DOM interface:
interface HTMLCommandElement : HTMLElement {
           attribute DOMString type;
           attribute DOMString label;
           attribute DOMString icon;
           attribute boolean disabled;
           attribute boolean checked;
           attribute DOMString radiogroup;
  readonly attribute HTMLElement? command;
};

The command element represents a command that the user can invoke.

A command can be explicitly part of a context menu or toolbar, using the menu element. It can also be put anywhere else on a page, either just to define a keyboard shortcut, or to define a command that is then referenced from other command elements.

A command element that uses the type, label, icon, disabled, checked, radiogroup, and title attributes defines a new command. A command element that uses the command attribute defines a command by reference to another one. This allows authors to define a command once, and set its state (e.g. whether it is active or disabled) in one place, and have all references to that command in the user interface change at the same time.


The type attribute indicates the kind of command: either a normal command with an associated action, or a state or option that can be toggled, or a selection of one item from a list of items.

The attribute is an enumerated attribute with three keywords and states. The "command" keyword maps to the Command state, the "checkbox" keyword maps to the Checkbox state, and the "radio" keyword maps to the Radio state. The missing value default is the Command state.

The Command state

The element represents a normal command with an associated action.

The Checkbox state

The element represents a state or option that can be toggled.

The Radio state

The element represents a selection of one item from a list of items.

The label attribute gives the name of the command, as shown to the user. The label attribute must be specified and must have a value that is not the empty string.

The title attribute gives a hint describing the command, which might be shown to the user to help him.

The icon attribute gives a picture that represents the command. If the attribute is specified, the attribute's value must contain a valid non-empty URL potentially surrounded by spaces.

The disabled attribute is a boolean attribute that, if present, indicates that the command is not available in the current state.

The distinction between disabled and hidden is subtle. A command would be disabled if, in the same context, it could be enabled if only certain aspects of the situation were changed. A command would be marked as hidden if, in that situation, the command will never be enabled. For example, in the context menu for a water faucet, the command "open" might be disabled if the faucet is already open, but the command "eat" would be marked hidden since the faucet could never be eaten.

The checked attribute is a boolean attribute that, if present, indicates that the command is selected. The attribute must be omitted unless the type attribute is in either the Checkbox state or the Radio state.

The radiogroup attribute gives the name of the group of commands that will be toggled when the command itself is toggled, for commands whose type attribute has the value "radio". The scope of the name is the child list of the parent element. The attribute must be omitted unless the type attribute is in the Radio state.


If a command element slave has a command attribute, and slave is in a Document, and there is an element in that Document whose ID has a value equal to the value of slave's command attribute, and the first such element in tree order, hereafter master, itself defines a command and either is not a command element or does not itself have a command attribute, then the master command of slave is master.

An element with a command attribute must have a master command and must not have any type, label, icon, disabled, checked, or radiogroup attributes.


The type IDL attribute must reflect the content attribute of the same name, limited to only known values.

The label, icon, disabled, checked, and radiogroup IDL attributes must reflect the respective content attributes of the same name.

command elements are not rendered unless they form part of a menu.

Here is an example of a toolbar with three buttons that let the user toggle between left, center, and right alignment. One could imagine such a toolbar as part of a text editor. The toolbar also has a separator followed by another button labeled "Publish", though that button is disabled.

<menu type="toolbar">
 <command type="radio" radiogroup="alignment" checked="checked"
          label="Left" icon="icons/alL.png" onclick="setAlign('left')">
 <command type="radio" radiogroup="alignment"
          label="Center" icon="icons/alC.png" onclick="setAlign('center')">
 <command type="radio" radiogroup="alignment"
          label="Right" icon="icons/alR.png" onclick="setAlign('right')">
 <hr>
 <command type="command" disabled
          label="Publish" icon="icons/pub.png" onclick="publish()">
</menu>