Interactive elements

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

[=Allowed ARIA role attribute values=]:

group role (default - do not set)

[=Allowed ARIA state and property attributes=]:

Global aria-* attributes

Any aria-* attributes applicable to the default role.

DOM interface:

        interface HTMLDetailsElement : HTMLElement {
          attribute boolean open;
        };
      

The <{details}> element is not appropriate for footnotes. Please see [[#footnotes]] for details on how to mark up footnotes.

The legend text should be presented in the language determined from the computed language of the element, if available, rather than from the locale of the browser/system.

This ability to request that additional information be shown or hidden may simply be the activation behavior of the appropriate summary element, in the case such an element exists. However, if no such element exists, user agents can still provide this ability through some other user interface affordance.

1. If another task has been queued to run the details notification task steps for this <{details}> element, then abort these steps.

   When the open attribute is toggled several times in succession, these steps essentially get coalesced so that only one event is fired.

2. Fire a simple event named toggle at the <{details}> element.

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

[=Allowed ARIA role attribute values=]:

button.

[=Allowed ARIA state and property attributes=]:

Global aria-* attributes

Any aria-* attributes applicable to the button role.

DOM interface:

Uses {{HTMLElement}}.

The activation behavior of summary elements is to run the following steps:

1. If this summary element has no parent node, then abort these steps.
2. Let parent be this summary element's parent node.
3. If parent is not a details element, then abort these steps.
4. If the open attribute is present on parent, then remove it. Otherwise, set parent's open attribute to the empty string.

   This will then run the details notification task steps.

Commands

Facets

• The Hidden State facet is false (visible)
• The element is in a Document that has an associated browsing context.
• Neither the element nor any of its ancestors has a <{global/hidden}> attribute specified.

Using the <{a}> element to define a command

Using the <{button}> element to define a command

Using the <{input}> element to define a command

• If the type attribute is in one of the <{input/Submit|Submit Button}>, <{input/Reset|Reset Button}>, <{input/Image|Image Button}>, or <{input/Button}> states, then the Label is the string given by the value attribute, if any, and a user agent-dependent, locale-dependent value that the user agent uses to label the button itself if the attribute is absent.
• Otherwise, if the element is a labeled control, then the Label is the string given by the {{Node/textContent}} of the first <{label}> element in tree order whose labeled control is the element in question. (In DOM terms, this is the string given by element.labels[0].textContent.)
• Otherwise, if the value attribute is present, then the Label is the value of that attribute.
• Otherwise, the Label is the empty string.

Using the <{option}> element to define a command

Using the accesskey attribute on a <{label}> element to define a command

Using the accesskey attribute on a <{legend}> element to define a command

Using the accesskey attribute to define a command on other elements

1. Run the focusing steps for the element.
2. If the element has a defined activation behavior, run synthetic click activation steps on the element.
3. Otherwise, if the element does not have a defined activation behavior, fire a click event at the element.

The dialog element

Categories:

Flow content.

Sectioning root.

Contexts in which this element can be used:

Where flow content is expected.

Content model:

Flow content.

Tag omission in text/html:

Neither tag is omissible

Content attributes:

Global attributes

open - Whether the dialog box is showing

[=Allowed ARIA role attribute values=]:

dialog (default - do not set) or alertdialog.

[=Allowed ARIA state and property attributes=]:

Global aria-* attributes

Any aria-* attributes applicable to the dialog roles.

DOM interface:

        interface HTMLDialogElement : HTMLElement {
          attribute boolean open;
          attribute DOMString returnValue;
          void show(optional (MouseEvent or Element) anchor);
          void showModal(optional (MouseEvent or Element) anchor);
          void close(optional DOMString returnValue);
        };
      

The following is an example of a modal <{dialog}> which provides a form for a user to add coins to their wallet, as part of an online game.

<div> <!-- body content --> </div> <dialog> <h1>Add to Wallet</h1> <label for="num">How many gold coins do you want to add to your wallet?</label> <div><input name="amt" id="num" type="number" min="0" step="0.01" value="100"></div> <p><strong>You add coins at your own risk.</strong></p> <div><label><input name="round" type="checkbox">Only add perfectly round coins</label></div> <div><input type="button" onclick="submit()" value="Add Coins"></div> </dialog>

dialog . show( [ anchor ] )

Displays the <{dialog}> element. The argument, if provided, provides an anchor point to which the element will be fixed.

dialog . showModal( [ anchor ] )

Displays the <{dialog}> element and makes it the top-most modal dialog. The argument, if provided, provides an anchor point to which the element will be fixed. This method honors the <{formelements/autofocus}> attribute.

dialog . close( [ result ] )

Closes the <{dialog}> element. The argument, if provided, provides a return value.

dialog . {{HTMLDialogElement/returnValue}} [ = result ]

Returns the dialog's return value. Can be set, to update the return value.

1. If the element already has an open attribute, then abort these steps.
2. Add an open attribute to the dialog element, whose value is the empty string.
3. If the show() method was invoked with an argument, set up the position of the <{dialog}> element, using that argument as the anchor. Otherwise, set the dialog to the normal alignment mode.
4. Run the dialog focusing steps for the <{dialog}> element.

1. Let subject be the <{dialog}> element on which the method was invoked.
2. If subject already has an open attribute, then throw an {{InvalidStateError}} exception and abort these steps.
3. If subject is not in a Document, then throw an {{InvalidStateError}} exception and abort these steps.
4. Add an open attribute to subject, whose value is the empty string.
5. If the showModal() method was invoked with an argument, set up the position of subject, using that argument as the anchor. Otherwise, set the dialog to the centered alignment mode.
6. Let subject's node document be blocked by the modal dialog subject.
7. Push subject onto subject's node document's pending dialog stack.
8. Run the dialog focusing steps for subject.

1. If for some reason subject is not a control group owner at this point, or if it is inert, abort these steps.
2. Let control be the first non-inert focusable area in subject's control group whose DOM anchor has an <{formelements/autofocus}> attribute specified. If there isn't one, then let control be subject.
3. Run the focusing steps for control.

1. Let subject be that <{dialog}> element and document be the Document from which it is being removed.
2. Remove subject from document's pending dialog stack.
3. If document's pending dialog stack is not empty, then let document be blocked by the modal dialog that is at the top of document's pending dialog stack. Otherwise, let document be no longer blocked by a modal dialog at all.

1. If subject does not have an open attribute, then abort these steps.
2. Remove subject's open attribute.
3. If the argument result was provided, then set the {{HTMLDialogElement/returnValue}} attribute to the value of result.
4. If subject is in its Document's pending dialog stack, then run these substeps:
   1. Remove subject from that pending dialog stack.
   2. If that pending dialog stack is not empty, then let subject's node document be blocked by the modal dialog that is at the top of the pending dialog stack. Otherwise, let document be no longer blocked by a modal dialog at all.
5. Queue a task to fire a simple event named close at subject.

An example of such a UI mechanism would be the user pressing the "Escape" key.

1. If anchor is a MouseEvent object, then run these substeps:
   1. If anchor's target element does not have a rendered box, or is in a different document than subject, then let subject be in the centered alignment mode, and abort the set up the position steps.
   2. Let anchor element be an anonymous element rendered as a box with zero 'height' and 'width' (so its 'margin' and border boxes both just form a point), positioned so that its top and left are at the coordinate identified by the event, and whose properties all compute to their initial values.
   Otherwise, let anchor element be anchor.

If an element to which another element is anchored changes rendering, the anchored element will be repositioned accordingly. (In other words, the requirements above are live, they are not just calculated once per anchored element.)