menuitem element

If you don't know what an element is or how you must use it, I recommend you read the "HTML tags and attributes" tutorial that you can find in the HTML tutorials section.

Table of contents

Description

The menuitem element represents a command in a menu. Menus have been designed to increase interactivity in application-like documents, allowing authors to provide commands that users can execute by clicking their labels. These menus are usually displayed on top of the application or deployed under user request (like, for example, by right-clicking on an element).

A menuitem can be declared to define a command, by setting its nature or behavior with the attributes type, label, icon, disabled, checked, radiogroup and default. In such case, the element is required to have a non empty label, which can be defined through the label attribute or through its content.

In the other hand, it can also be used to make a reference to another existing command, by omitting all attributes except command. In the latter case, the command attribute should match the id attribute of the menuitem element it's referring to.

This feature allows authors to create one command and then instantiate it at different locations. The changes made to a master command are immediately reflected on all commands referring to it.

When a menuitem element is declared to define a command, it can be of three different types, according to the value of its type attribute. The values it can take are (case-insensitive):

  • command: the element represents a command with an associated action. This is the default value.
  • checkbox: the element represents a value or option that can be toggled (on/off). With this configuration the command behaves like a checkbox.
  • radio: the element represents an option that belongs to a group of options, composed by one or more commands sharing the same value in the radiogroup attribute. With this configuration the command behaves like a radio button.

The text that will represent the command in the menu is provided by the label attribute. Optionally, an icon can be provided (by declaring its location in the icon attribute) that, in most cases, will be rendered next to the command's label.

When declared in this element, the title attribute has a special meaning, as it's used to describe the purpose of the command.

As of 2015/03/27, browser support for the menu element is almost inexistent. Authors may have to rely on scripts to achieve the same effect cross-browser, until support grows.

Examples

In our first example, we'll create a context menu for a paragraph (p). This menu will be shown in supporting browsers when the user right-clicks over the paragraph. The actions executed by each menuitem will be performed by a client-side script called in the onclick attribute.

<p id="paragraph1" contextmenu="contextmenu1">A custom context menu should be displayed in supporting browsers, when the user right-clicks this paragraph, allowing the selection of the background color.</p>
<menu id="contextmenu1" type="context">
  <menuitem label="Red background" onclick="menuChangeColorTo(1, 'red')"></menuitem>
  <menuitem label="Green background" onclick="menuChangeColorTo(1, 'green')"></menuitem>
  <menuitem label="Blue background" onclick="menuChangeColorTo(1, 'blue')"></menuitem>
</menu>

A custom context menu should be displayed in supporting browsers, when the user right-clicks this paragraph, allowing the selection of the background color.

Now we'll add icons to the commands defined in this custom menu. To do so, the URI of the image that will act as icon must be specified in the icon attribute of the menuitem.

The functions declared in the following example aren't meant to work. This example aims only to show how browsers render icons in a menu.

<p contextmenu="contextmenu2">World War I, also known as the First World War or the Great War, was a global war centered in Europe that began on 28 July 1914 and lasted until 11 November 1918. More than 9 million combatants and 7 million civilians died as a result of the war, a casualty rate exacerbated by the belligerents' technological and industrial sophistication, and tactical stalemate.</p>
<menu id="contextmenu2" type="context">
  <menuitem label="Cut" icon="/assets/images/cut-icon.png" onclick="cut()"></menuitem>
  <menuitem label="Copy" icon="/assets/images/copy-icon.png" onclick="copy()"></menuitem>
  <menuitem label="Paste" icon="/assets/images/paste-icon.png" onclick="paste()"></menuitem>
</menu>

World War I, also known as the First World War or the Great War, was a global war centered in Europe that began on 28 July 1914 and lasted until 11 November 1918. More than 9 million combatants and 7 million civilians died as a result of the war, a casualty rate exacerbated by the belligerents' technological and industrial sophistication, and tactical stalemate.

Lastly, we'll tweak some attributes in the menuitem elements to provide options that behave like checkboxes and radio buttons. To do this, we'll declare the first menuitem with the value "checkbox" in its type attribute, while the last three commands will have the "radio" value in the type attribute and will share the same value in the radiogroup attribute.

The functions declared in the following example aren't meant to work. This example aims only to test the functionality provided by browsers for menus.

<p contextmenu="contextmenu3">World War II, also known as the Second World War, was a global war that lasted from 1939 to 1945, though related conflicts began earlier. It involved the vast majority of the world's nations (including all of the great powers) eventually forming two opposing military alliances: the Allies and the Axis.</p>
<menu id="contextmenu3" type="context">
  <menuitem type="checkbox" label="Autodetect input method"></menuitem>
  <hr>
  <menuitem type="radio" label="Slow input" radiogroup="speed"></menuitem>
  <menuitem type="radio" label="Medium input" radiogroup="speed"></menuitem>
  <menuitem type="radio" label="Fast input" radiogroup="speed"></menuitem>
</menu>

World War II, also known as the Second World War, was a global war that lasted from 1939 to 1945, though related conflicts began earlier. It involved the vast majority of the world's nations (including all of the great powers) eventually forming two opposing military alliances: the Allies and the Axis.

Attributes

Specific attributes

type

One of three predefined values defining the behavior and/or purpose of the command. The three possible (case-insensitive) values are:

  • command: the element represents a command with an associated action. This is the default value.
  • checkbox: the element represents a value or option that can be toggled (on/off). With this configuration the command behaves like a checkbox.
  • radio: the element represents an option that belongs to a group of options, composed by one or more commands sharing the same value in the radiogroup attribute. With this configuration the command behaves like a radio button.

Example

<menu id="checkcontextmenu" type="context">
  <menuitem type="checkbox" label="Check for conformance"></menuitem>
  <hr>
  <menuitem type="radio" label="HTML 4.01" radiogroup="standard"></menuitem>
  <menuitem type="radio" label="XHTML 1.0" radiogroup="standard"></menuitem>
  <menuitem type="radio" label="HTML5" radiogroup="standard"></menuitem>
</menu>

label

A run of text to be displayed by the menu as the label of this command.

The functions in the following example ("checkErrors" and "saveDraft") aren't meant to work. This example aims only to show how browsers display labels for the commands.

Example

<p contextmenu="contextmenu4">The abacus, also called a counting frame, is a calculating tool that was in use centuries before the adoption of the written modern numeral system and is still widely used by merchants, traders and clerks in Asia, Africa, and elsewhere.</p>
<menu id="contextmenu4" type="context">
  <menuitem label="Check for errors" onclick="checkErrors()"></menuitem>
  <menuitem label="Save a draft" onclick="saveDraft()"></menuitem>
</menu>

The abacus, also called a counting frame, is a calculating tool that was in use centuries before the adoption of the written modern numeral system and is still widely used by merchants, traders and clerks in Asia, Africa, and elsewhere.

icon

The URI of an image that will represent visually the command's purpose. This image will be usally displayed next to the label of the command.

The function in the following example isn't meant to work. This example aims only to show how browsers display icons for the commands.

Example

<p contextmenu="contextmenu5">Quantum computing studies theoretical computation systems (quantum computers) that make direct use of quantum-mechanical phenomena, such as superposition and entanglement, to perform operations on data.</p>
<menu id="contextmenu5" type="context">
  <menuitem label="Auto-fix" icon="/assets/images/autofix-icon.png" onclick="autofix()"></menuitem>
</menu>

Quantum computing studies theoretical computation systems (quantum computers) that make direct use of quantum-mechanical phenomena, such as superposition and entanglement, to perform operations on data.

disabled

A boolean value indicating wether the command is disabled or not. If the attribute takes the value "disabled" or the empty string (""), or if it's just present, the command will be disabled.

Disabled commands are rendered greyed out (if visible) and users aren't allowed to interact with them in any way.

Example

<p contextmenu="contextmenu6">Wilhelm Conrad Rontgen was a German physicist, who, on 8 November 1895, produced and detected electromagnetic radiation in a wavelength range known as X-rays, an achievement that earned him the first Nobel Prize in Physics in 1901.</p>
<menu id="contextmenu6" type="context">
  <menuitem label="Delete all" onclick="deleteAll()" disabled></menuitem>
</menu>

Wilhelm Conrad Rontgen was a German physicist, who, on 8 November 1895, produced and detected electromagnetic radiation in a wavelength range known as X-rays, an achievement that earned him the first Nobel Prize in Physics in 1901.

checked

A boolean value indicating whether this "checkbox" or "radio" type command will be initially checked or not. If this attribute has the value "checked" or the empty string (""), or if it's just present, the command will be initially checked.

Example

<p contextmenu="contextmenu7">David was, according to the books of Samuel, the second king of the United Kingdom of Israel, and according to the Gospels of Matthew and Luke, an ancestor of Jesus.</p>
<menu id="contextmenu7" type="context">
  <menuitem type="checkbox" label="Update automatically" checked></menuitem>
  <menuitem type="checkbox" label="Input assistant"></menuitem>
</menu>

David was, according to the books of Samuel, the second king of the United Kingdom of Israel, and according to the Gospels of Matthew and Luke, an ancestor of Jesus.

radiogroup

A token providing the name of the group this "radio" type command belongs to. All commands with the same value in this attribute will be part of the same group of options.

In a group of commands only one command can be selected at a time. When selecting a command, all other commands in the group will be deselected.

Example

<p contextmenu="contextmenu8">The Beatles were an English rock band that formed in Liverpool in 1960. With members John Lennon, Paul McCartney, George Harrison and Ringo Starr, they became widely regarded as the greatest and most influential act of the rock era.</p>
<menu id="contextmenu8" type="context">
  <menuitem type ="radio" label="Low contrast" radiogroup="contrast"></menuitem>
  <menuitem type ="radio" label="Hight contrast" radiogroup="contrast"></menuitem>
</menu>

The Beatles were an English rock band that formed in Liverpool in 1960. With members John Lennon, Paul McCartney, George Harrison and Ringo Starr, they became widely regarded as the greatest and most influential act of the rock era.

default

A boolean value indicating whether this command is the default command or not. If this attribute has the value "default" or the empty string (""), or if it's just present, the command will be the default option.

Default commands are executed when the user directly activates the menu label instead of deploying its list of commands.

The functions in the following example ("saveOverwrite" y "saveNewName") aren't meant to work. This example aims only to show the functionality provided by browsers for menus.

Example

<menu id="savecontextmenu" type="context">
  <menu label="Save">
    <menuitem label="Overwriting" onclick="saveOverwrite()" default></menuitem>
    <menuitem label="Using new name" onclick="saveNewName()"></menuitem>
  </menu>
</menu>

command

A token matching the content of the id attribute of the command this element is referring to. This attribute sets the element as a reference to another menuitem that has been declared to define a command.

This feature allows authors to create one command and then instantiate it at different locations. The changes made to a master command are immediately reflected on all commands referring to it.

The functions in the following example ("new", "save", "print" y "close") aren't meant to work. This example aims only to show the functionality provided by browsers for menus.

Example

<p contextmenu="quickmenu">John Ronald Reuel Tolkien, was an English writer, poet, philologist, and university professor who is best known as the author of the classic high-fantasy works The Hobbit, The Lord of the Rings, and The Silmarillion.</p>
<menu id="quickmenu" type="context">
  <menuitem command="menunew"></menuitem>
  <menuitem command="menuclose"></menuitem>
</menu>
<menu id="extendedmenu" type="context">
  <menuitem id="menunew" label="New" onclick="new()"></menuitem>
  <menuitem id="menusave" label="Save" onclick="save()"></menuitem>
  <menuitem id="menuprint" label="Print" onclick="print()"></menuitem>
  <menuitem id="menuclose" label="Close" onclick="close()"></menuitem>
</menu>

John Ronald Reuel Tolkien, was an English writer, poet, philologist, and university professor who is best known as the author of the classic high-fantasy works The Hobbit, The Lord of the Rings, and The Silmarillion.

Global attributes

For information about global attributes refer to this list of global attributes in HTML5.

Events

Global events

For information about global events refer to this list of global events in HTML5.