Cookies on ons.gov.uk

Cookies are small files stored on your device when you visit a website. We use some essential cookies to make this website work.

We would like to set additional cookies to remember your settings and understand how you use the site. This helps us to improve our services.

You have accepted all additional cookies. You have rejected all additional cookies. You can change your cookie preferences at any time.

Skip to main content

Details

Overview

Use the details component to make a page easier to read by condensing information that is only needed by some users.

Example Details contents

Nunjucks

{% from "components/details/_macro.njk" import onsDetails %}

{{
    onsDetails({
        "id": "details-example",
        "title": "What is a photovoltaic system?",
        "content": "<p>A typical photovoltaic system employs solar panels, each comprising a number of solar cells, which generate electrical power. PV installations may be ground-mounted, rooftop mounted or wall mounted. The mount may be fixed, or use a solar tracker to follow the sun across the sky.</p>"
    })
}}

Nunjucks macro options

NameTypeRequiredDescription
idstringtrueHTML id attribute for the details
classesstringfalseClasses to add to the details outer element
titlestringtrueThe title text for the details heading
headingLevelintfalseNumber used to determine the heading level of the title text. Use to ensure the title has a correct semantic order on the page. Defaults to 2
contentstringtrueHTML content for the details
saveStatebooleanfalseSaves the opened state of the details to local storage so it remains open when the page reloads
openbooleanfalseForces the details to be open when the page loads
attributesobjectfalseHTML attributes (for example, data attributes) to add to the details
headingAttributesobjectfalseHTML attributes (for example, data attributes) to add to the details header element
contentAttributesobjectfalseHTML attributes (for example, data attributes) to add to the details content element

HTML

<div id="details-example" class="ons-details ons-js-details">
  <div class="ons-details__heading ons-js-details-heading" role="button">
    <h2 class="ons-details__title ons-u-fs-r--b">What is a photovoltaic system?</h2>
    <span class="ons-details__icon">
      <svg class="ons-icon" viewBox="0 0 8 13" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor"
        role="img" title="ons-icon-chevron">
        <path
          d="M5.74,14.28l-.57-.56a.5.5,0,0,1,0-.71h0l5-5-5-5a.5.5,0,0,1,0-.71h0l.57-.56a.5.5,0,0,1,.71,0h0l5.93,5.93a.5.5,0,0,1,0,.7L6.45,14.28a.5.5,0,0,1-.71,0Z"
          transform="translate(-5.02 -1.59)" />
      </svg></span>
  </div>
  <div id="details-example-content" class="ons-details__content ons-js-details-content">
    <p>A typical photovoltaic system employs solar panels, each comprising a number of solar cells, which generate
      electrical power. PV installations may be ground-mounted, rooftop mounted or wall mounted. The mount may be fixed,
      or use a solar tracker to follow the sun across the sky.</p>
  </div>
</div>

When to use this component

The details component can be used to condense a single block of content into a selectable heading, allowing the user to reveal it if they need it.

Good uses of the component are:

  • to reveal additional help at the point where a user may need it, for example, to help answer a question
  • to reveal information only needed by a first-time user
  • to show the definition of a term that may not be well understood

When not to use this component

Do not use the details component to hide information that most of your users will need to progress with their task.

If you need to use more than one details component together on a page, use an accordion.

If users need to be able to quickly switch between blocks of closely related content, use tabs.

How this component works

This component contains the data-ga-action="Open/Close panel" attribute, so you will not need to add this for Google Analytics tracking.

How to use this component

The details component uses JavaScript so when it is turned off, the content is expanded and displayed as a standard heading and block of content.

Use an appropriate heading tag (h2, h3 etc) for the titleTag to provide the correct semantic hierarchy to the document with the rest of the page. The default is H2 if titleTag is not provided.

Use a clear label

The details component hides content so make sure your heading is clear so the user doesn’t need to work hard to understand if they need to expand it.

Google analytics

If you would like to track more detailed information about interactions with this component, use these attributes:

  • data-ga="click"
  • data-ga-category="definition"
  • data-ga-label="{TITLE}"

For more information, see our guidance on customising your Google Analytics tracking.

Variants

Details component with save state enabled

Use this when you need to include a link or call to action within a details component that does not open in a new window.

This will make sure that the component remains expanded if the user returns to the page using the back button in their browser.

Example Details With Saved State contents

Nunjucks
{% from "components/details/_macro.njk" import onsDetails %}

{{
    onsDetails({
        "id": "details-with-save",
        "title": "What is a photovoltaic system?",
        "content": "<p>A typical photovoltaic system employs solar panels, each comprising a number of solar cells, which generate electrical power. PV installations may be ground-mounted, rooftop mounted or wall mounted. The mount may be fixed, or use a solar tracker to follow the sun across the sky.</p>",
        "saveState": "true"
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringtrueHTML id attribute for the details
classesstringfalseClasses to add to the details outer element
titlestringtrueThe title text for the details heading
headingLevelintfalseNumber used to determine the heading level of the title text. Use to ensure the title has a correct semantic order on the page. Defaults to 2
contentstringtrueHTML content for the details
saveStatebooleanfalseSaves the opened state of the details to local storage so it remains open when the page reloads
openbooleanfalseForces the details to be open when the page loads
attributesobjectfalseHTML attributes (for example, data attributes) to add to the details
headingAttributesobjectfalseHTML attributes (for example, data attributes) to add to the details header element
contentAttributesobjectfalseHTML attributes (for example, data attributes) to add to the details content element
HTML
<div id="details-with-save" class="ons-details ons-js-details" data-save-state="true">
  <div class="ons-details__heading ons-js-details-heading" role="button">
    <h2 class="ons-details__title ons-u-fs-r--b">What is a photovoltaic system?</h2>
    <span class="ons-details__icon">
      <svg class="ons-icon" viewBox="0 0 8 13" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor"
        role="img" title="ons-icon-chevron">
        <path
          d="M5.74,14.28l-.57-.56a.5.5,0,0,1,0-.71h0l5-5-5-5a.5.5,0,0,1,0-.71h0l.57-.56a.5.5,0,0,1,.71,0h0l5.93,5.93a.5.5,0,0,1,0,.7L6.45,14.28a.5.5,0,0,1-.71,0Z"
          transform="translate(-5.02 -1.59)" />
      </svg></span>
  </div>
  <div id="details-with-save-content" class="ons-details__content ons-js-details-content">
    <p>A typical photovoltaic system employs solar panels, each comprising a number of solar cells, which generate
      electrical power. PV installations may be ground-mounted, rooftop mounted or wall mounted. The mount may be fixed,
      or use a solar tracker to follow the sun across the sky.</p>
  </div>
</div>

Nesting other components in a details component

You can use other components inside of the details component.

An example of this is the details component with a warning panel:

Example Details With Warning contents

Nunjucks
{% from "components/details/_macro.njk" import onsDetails %}
{% from "components/panel/_macro.njk" import onsPanel %}

{%
    call onsDetails({
        "id": "details-example-with-warning",
        "title": "Need to answer separately from your household?"
    })
%}
    <p>
        If you need to answer separately from the people you live with, you can <a href="#0">request an individual access code</a> to start
        a separate survey.
    </p>
    {%
        call onsPanel({
            "variant": "warn"
        })
    %}
        Someone in your household must still complete a survey using a household access code
    {% endcall %}
{% endcall %}
Nunjucks macro options
NameTypeRequiredDescription
idstringtrueHTML id attribute for the details
classesstringfalseClasses to add to the details outer element
titlestringtrueThe title text for the details heading
headingLevelintfalseNumber used to determine the heading level of the title text. Use to ensure the title has a correct semantic order on the page. Defaults to 2
contentstringtrueHTML content for the details
saveStatebooleanfalseSaves the opened state of the details to local storage so it remains open when the page reloads
openbooleanfalseForces the details to be open when the page loads
attributesobjectfalseHTML attributes (for example, data attributes) to add to the details
headingAttributesobjectfalseHTML attributes (for example, data attributes) to add to the details header element
contentAttributesobjectfalseHTML attributes (for example, data attributes) to add to the details content element
HTML
<div id="details-example-with-warning" class="ons-details ons-js-details">
  <div class="ons-details__heading ons-js-details-heading" role="button">
    <h2 class="ons-details__title ons-u-fs-r--b">Need to answer separately from your household?</h2>
    <span class="ons-details__icon">
      <svg class="ons-icon" viewBox="0 0 8 13" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor"
        role="img" title="ons-icon-chevron">
        <path
          d="M5.74,14.28l-.57-.56a.5.5,0,0,1,0-.71h0l5-5-5-5a.5.5,0,0,1,0-.71h0l.57-.56a.5.5,0,0,1,.71,0h0l5.93,5.93a.5.5,0,0,1,0,.7L6.45,14.28a.5.5,0,0,1-.71,0Z"
          transform="translate(-5.02 -1.59)" />
      </svg></span>
  </div>
  <div id="details-example-with-warning-content" class="ons-details__content ons-js-details-content">
    <p> If you need to answer separately from the people you live with, you can <a href="#0">request an individual
        access code</a> to start a separate survey. </p>
    <div class="ons-panel ons-panel--warn ons-panel--no-title">
      <span class="ons-panel__icon" aria-hidden="true">!</span>
      <span class="ons-panel__assistive-text ons-u-vh">Warning: </span>
      <div class="ons-panel__body"> Someone in your household must still complete a survey using a household access code
      </div>
    </div>
  </div>
</div>
Warning:

Do not use this for content that is important to every user

Only use a warning panel inside of a details component to warn users about something that it is only relevant to those that have opened the details component.

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss the ‘Collapsible’ component on GitHub (opens in a new tab)