Details

Problem

Pages with a lot of form elements without grouping and hierarchy are confusing and hard to use and get used to. Some form elements are not important enough to see all the time.

Solution

Group related form elements with a detail.
A detail is placed around these form elements. Depending on the browser, a detail will be collapsible.

Use when

• There are a lot of form elements which need to be grouped logically
• There are very different form elements on a page
• There are very similar form elements, but with a distinctive difference

Recommendations

• Don't put a detail around the main (first) interaction on the page if there is one
• Keep the label short and concrete
• detail contents should stay within 1 page scroll
• Avoid nested details, it disorients the user
• Position default-collapsed details below expanded ones
• If a detail is collapsible, the default state should be collapsed (if it's that important to show its content initially, don't make it collapsible)

When to use Fieldsets over Details

• When they are semantically related like a date field with year, month, day, time.

API

\Drupal\Core\Render\Element\Details