4.11 Interactive elements

4.11.1 The details element

Categories:
Flow content.
Sectioning root.
Interactive content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
One summary element followed by flow content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
open — Whether the details are visible
DOM interface:
interface HTMLDetailsElement : HTMLElement {
           attribute boolean open;
};

The details element represents a disclosure widget from which the user can obtain additional information or controls.

The details element is not appropriate for footnotes. Please see the section on footnotes for details on how to mark up footnotes.

The summary element child of the element, if any, represents the summary or legend of the details.

The rest of the element's contents represents the additional information or controls.

The open content attribute is a boolean attribute. If present, it indicates that both the summary and the additional information is to be shown to the user. If the attribute is absent, only the summary is to be shown.

The following example shows the details element being used to hide technical details in a progress report.

<section class="progress window">
 <h1>Copying "Really Achieving Your Childhood Dreams"</h1>
 <details>
  <summary>Copying... <progress max="375505392" value="97543282"></progress> 25%</summary>
  <dl>
   <dt>Transfer rate:</dt> <dd>452KB/s</dd>
   <dt>Local filename:</dt> <dd>/home/rpausch/raycd.m4v</dd>
   <dt>Remote filename:</dt> <dd>/var/www/lectures/raycd.m4v</dd>
   <dt>Duration:</dt> <dd>01:16:27</dd>
   <dt>Color profile:</dt> <dd>SD (6-1-6)</dd>
   <dt>Dimensions:</dt> <dd>320×240</dd>
  </dl>
 </details>
</section>

The following shows how a details element can be used to hide some controls by default:

<details>
 <summary><label for=fn>Name & Extension:</label></summary>
 <p><input type=text id=fn name=fn value="Pillar Magazine.pdf">
 <p><label><input type=checkbox name=ext checked> Hide extension</label>
</details>

One could use this in conjunction with other details in a list to allow the user to collapse a set of fields down to a small set of headings, with the ability to open each one.

In these examples, the summary really just summarises what the controls can change, and not the actual values, which is less than ideal.

Because the open attribute is added and removed automatically as the user interacts with the control, it can be used in CSS to style the element differently based on its state. Here, a stylesheet is used to animate the color of the summary when the element is opened or closed:

<style>
 details > summary { transition: color 1s; color: black; }
 details[open] > summary { color: red; }
</style>
<details>
 <summary>Automated Status: Operational</summary>
 <p>Velocity: 12m/s</p>
 <p>Direction: North</p>
</details>

4.11.2 The summary element

Categories:
None.
Contexts in which this element can be used:
As the first child of a details element.
Content model:
Either: phrasing content.
Or: one element of heading content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

The summary element represents a summary, caption, or legend for the rest of the contents of the summary element's parent details element.

4.11.3 The menu element

Categories:
Flow content.
If the element's type attribute is in the toolbar state: Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
If the element's type attribute is in the popup menu state: as the child of a menu element whose type attribute is in the popup menu state.
Content model:
If the element's type attribute is in the toolbar state: either zero or more li and script-supporting elements, or, flow content.
If the element's type attribute is in the popup menu state: in any order, zero or more menuitem elements, zero or more hr elements, zero or more menu elements whose type attributes are in the popup menu state, and zero or more script-supporting elements.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
type — Type of menu
label — User-visible label
DOM interface:
interface HTMLMenuElement : HTMLElement {
           attribute DOMString type;
           attribute DOMString label;
};

The menu element represents a list of commands.

The type attribute is an enumerated attribute indicating the kind of menu being declared. The attribute has two states. The popup keyword maps to the popup menu state, in which the element is declaring a context menu or the menu for a menu button. The toolbar keyword maps to the toolbar state, in which the element is declaring a toolbar. The attribute may also be omitted. The missing value default is the popup menu state if the parent element is a menu element whose type attribute is in the popup menu state; otherwise, it is the toolbar state.

If a menu element's type attribute is in the popup menu state, then the element represents the commands of a popup menu, and the user can only examine and interact with the commands if that popup menu is activated through some other element, either via the contextmenu attribute or the button element's menu attribute.

If a menu element's type attribute is in the toolbar state, then the element represents a toolbar consisting of its contents, in the form of either an unordered list of items (represented by li elements), each of which represents a command that the user can perform or activate, or, if the element has no li element children, flow content describing available commands.

The label attribute gives the label of the menu. It is used by user agents to display nested menus in the UI: a context menu containing another menu would use the nested menu's label attribute for the submenu's menu label. The label attribute must only be specified on menu elements whose parent element is a menu element whose type attribute is in the popup menu state.

In this example, the menu element is used to describe a toolbar with three menu buttons on it, each of which has a dropdown menu with a series of options:

<menu> 
 <li>
  <button type=menu value="File" menu="filemenu">
  <menu id="filemenu" type="popup">
   <menuitem onclick="fnew()" label="New...">
   <menuitem onclick="fopen()" label="Open...">
   <menuitem onclick="fsave()" label="Save">
   <menuitem onclick="fsaveas()" label="Save as...">
  </menu>
 </li>
 <li>
  <button type=menu value="Edit" menu="editmenu">
  <menu id="editmenu" type="popup">
   <menuitem onclick="ecopy()" label="Copy">
   <menuitem onclick="ecut()" label="Cut">
   <menuitem onclick="epaste()" label="Paste">
  </menu>
 </li>
 <li>
  <button type=menu value="Help" menu="helpmenu">
  <menu id="helpmenu" type="popup">
   <menuitem onclick="location='help.html'" label="Help">
   <menuitem onclick="location='about.html'" label="About">
  </menu>
 </li>
</menu>

In a supporting user agent, this might look like this (assuming the user has just activated the second button):

A toolbar with three buttons, labeled 'File', 'Edit', and 'Help'; where if you select the 'Edit' button you get a drop-down menu with three more options, 'Copy', 'Cut', and 'Paste'.

4.11.4 The menuitem element

Categories:
None.
Contexts in which this element can be used:
As a child of a menu element whose type attribute is in the popup menu state.
Content model:
Empty.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
type — Type of command
label — User-visible label
icon — Icon for the command
disabled — Whether the form control is disabled
checked — Whether the command or control is checked
radiogroup — Name of group of commands to treat as a radio button group
default — Mark the command as being a default command
command — Command definition
Also, the title attribute has special semantics on this element: Hint describing the command.
DOM interface:
interface HTMLMenuItemElement : HTMLElement {
           attribute DOMString type;
           attribute DOMString label;
           attribute DOMString icon;
           attribute boolean disabled;
           attribute boolean checked;
           attribute DOMString radiogroup;
           attribute boolean default;
  readonly attribute HTMLElement? command;
};

The menuitem element represents a command that the user can invoke from a popup menu (either a context menu or the menu of a menu button).

A menuitem element that uses one or more of the type, label, icon, disabled, checked, and radiogroup attributes defines a new command.

A menuitem 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.

If the command attribute is specified, the element is in the indirect command mode. If it is not specified, it is in the explicit command mode. When the element is in the indirect command mode, the element must not have any of the following attributes specified: type, label, icon, disabled, checked, radiogroup.


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 if the element is in the explicit command mode. If the attribute is specified, it must have a value that is not the empty string.

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. When specified, the attribute's value must be a non-empty string.


If a menuitem element slave has a command attribute, and there is an element in slave's home subtree 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 menuitem element or does not itself have a command attribute, then the master command of slave is master.

A menuitem element with a command attribute must have a master command.

This effectively defines the syntax of the attribute's value as being the ID of another element that defines a command.


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

The default attribute indicates, if present, that the command is the one that would have been invoked if the user had directly activated the menu's subject instead of using the menu. The default attribute is a boolean attribute.

In this trivial example, a submit button is given a context menu that has two options, one to reset the form, and one to submit the form. The submit command is marked as being the default.

<form action="dosearch.pl">
 <p><label>Enter search terms: <input type="text" name="terms"></label></p>
 <p><input type=submit contextmenu=formmenu id="submitbutton"></p>
 <p hidden><input type=reset id="resetbutton"></p>
 <menu type=popup id=formmenu>
  <menuitem command="submitbutton" default>
  <menuitem command="resetbutton">
 </menu>
</form>

The menuitem element is not rendered except as part of a popup menu.

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

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

4.11.5 Context menus

4.11.5.1 Declaring a context menu

The contextmenu attribute gives the element's context menu. The value must be the ID of a menu element in the same home subtree whose type attribute is in the popup menu state.

When a user right-clicks on an element with a contextmenu attribute, the user agent will first fire a contextmenu event at the element, and then, if that event is not canceled, a show event at the menu element.

Here is an example of a context menu for an input control:

<form name="npc">
 <label>Character name: <input name=char type=text contextmenu=namemenu required></label>
 <menu type=popup id=namemenu>
  <menuitem label="Pick random name" onclick="document.forms.npc.elements.char.value = getRandomName()">
  <menuitem label="Prefill other fields based on name" onclick="prefillFields(document.forms.npc.elements.char.value)">
 </menu>
</form>

This adds two items to the control's context menu, one called "Pick random name", and one called "Prefill other fields based on name". They invoke scripts that are not shown in the example above.

In this example, an image of cats is given a context menu with four possible commands:

<img src="cats.jpeg" alt="Cats" contextmenu=catsmenu>
<menu type="popup" id="catsmenu">
 <menuitem label="Pet the kittens" onclick="kittens.pet()">
 <menuitem label="Cuddle with the kittens" onclick="kittens.cuddle()">
 <menu label="Feed the kittens">
  <menuitem label="Fish" onclick="kittens.feed(fish)">
  <menuitem label="Chicken" onclick="kittens.feed(chicken)">
 </menu>
</menu>

When a user of a mouse-operated visual Web browser right-clicks on the image, the browser might pop up a context menu like this:

A context menu, shown over a picture of cats, with four lines: the first two offering the menu items described in the markup above ('Pet the kittens' and 'Cuddle with the kittens'), the third giving a submenu labeled 'Feed the kittens', and the fourth, after a horizontal splitter, consisting of only a downwards-pointing disclosure triangle.

When the user clicks the disclosure triangle, such a user agent would expand the context menu in place, to show the browser's own commands:

This would result in the same basic interface, but with a longer menu; the disclosure triangle having been replaced by items such as 'View Image', 'Copy Image', 'Copy Image Location', and so forth.

4.11.5.2 The RelatedEvent interfaces
[Constructor(DOMString type, optional RelatedEventInit eventInitDict)]
interface RelatedEvent : Event {
  readonly attribute EventTarget? relatedTarget;
};

dictionary RelatedEventInit : EventInit {
  EventTarget? relatedTarget;
};
event . relatedTarget

Returns the other event target involved in this event. For example, when a show event fires on a menu element, the other event target involved in the event would be the element for which the menu is being shown.