HTML / Element

How to Use the optgroup Element

The HTML optgroup element groups related choices inside a select element. It helps people find a choice when a list contains many options.

The answer first

Use optgroup inside select to organize related option elements. Put the group name in label.

The optgroup itself cannot be selected. People select an option inside it. Use disabled when the whole group should be unavailable.

Minimal example

<label for="language">Language</label>
<select id="language" name="language">
  <optgroup label="Markup">
    <option value="html">HTML</option>
  </optgroup>
  <optgroup label="Programming">
    <option value="javascript">JavaScript</option>
  </optgroup>
</select>

Give the select a label, then use optgroup to classify its choices. The submitted value comes from the selected option, not from the group label.

Submitting this example sends a GET request to this page, with the selected option's value in the URL query. The group label only organizes the choices; it is not submitted.

Give the group a label

Use the label attribute for a short name that explains what the choices have in common. Examples include “Markup” and “Programming”.

<optgroup label="Markup">
  <option value="html">HTML</option>
  <option value="css">CSS</option>
</optgroup>

The group label does not replace the label for the select. Label the whole selection control so its purpose is clear before someone reaches an individual group.

Disable a group temporarily

optgroup disabled makes its option elements unavailable for user selection. This can show discontinued plans or regions that are not currently available.

<select name="plan">
  <optgroup label="Available">
    <option value="basic">Basic</option>
  </optgroup>
  <optgroup label="Discontinued" disabled>
    <option value="legacy">Legacy plan</option>
  </optgroup>
</select>

If people need to know why a choice is unavailable, include that state in the group name or nearby explanation. disabled keeps the choice visible while preventing interaction.

How it differs from option

Element	Role	Can it be selected?
`select`	The selection control as a whole	Operated as a control
`optgroup`	A named group of related choices	No
`option`	One choice and its value	Yes

An optgroup is not for creating nested levels of groups. Usually, put related option elements directly inside one group.

Common mistakes

Putting optgroup outside select. Normal optgroup elements are used inside select.
Assuming that the group label is a choice. Only the option elements can be selected.
Using the group label as the label for the whole select. Provide a separate label for the selection control.
Making unavailable choices look faint with CSS only. Use disabled when the unavailable state has meaning.
Replacing a native select with a custom JavaScript control without checking keyboard and assistive-technology support. Consider the native control first.

Going further

In a conventional select, the label attribute names the group. The current HTML Standard also defines a legend-based group-labeling mechanism for customizable select elements. Do not assume that conventional and customizable select rendering and accessibility behave identically.

Check it in Atlas

For label resolution, disabled boundaries, form-submission boundaries, the DOM API, customizable select, and accessibility mappings, see optgroup in Yugien Atlas. For the selection model as a whole, see Atlas on select; for individual choices, see Atlas on option.