Components Key details bar (retired)

This component was retired in September 2024 and should not be used in new projects. Use the Quick reference component instead.

This guidance is kept for reference by teams who are already using the key details bar. It is not updated or maintained.

When to use this component

This component is retired and should not be used in new projects. Use the Quick reference component instead.

The key details bar displays a small set of information – two or three data items – that users need to check before starting a task or refer to while doing it.

The basic component includes:

• Customer name
• National Insurance number
• An optional status tag

If your research shows that agents need more information, the bar can be extended by adding a lower block to include data such as a case reference, date of birth or postcode.

When not to use this component

The key details bar does not work well as banner to draw attention to important or urgent information.

Do not use the key details bar instead of an H1 heading.

The component’s high contrast means it quickly becomes harder to read as more text is added. Only use the extended version of the component if you have strong evidence of a genuine user need, and consider other solutions if usability is affected.

How it works

The standard key details bar includes two text items and an optional status tag. The text items should have a clear hierarchy: do not use the same style for multiple items.

Open this example in a new tab

<section class="dwp-key-details-bar" aria-label="Key details">
<div class="dwp-key-details-bar__key-details">
<dl class="dwp-key-details-bar__top-block">
  <dt class="govuk-visually-hidden">First item description:</dt>
  <dd class="dwp-key-details-bar__primary">First item</dd>
  <dt class="govuk-visually-hidden">Second item description:</dt>
  <dd class="dwp-key-details-bar__secondary">Second item</dd>
  <dt class="govuk-visually-hidden">Status description:</dt>
  <dd class="dwp-key-details-bar__status">
    <strong class="govuk-tag dwp-key-details-bar__status--dwp-default">
      Status
    </strong>
  </dd>
</dl>
</div>
</section>

Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as “Required” in the option description.

If you’re using Nunjucks macros in production with “html” options, or ones ending with “html”, you must sanitise the HTML to protect against cross-site scripting exploits.

Name	Type	Description
primaryIdentifier	object	Required. The primary identifier, see primaryIdentifier
secondaryIdentifier	object	The secondary identifier, see secondaryIdentifier
status	object	The claim status, see status
additionalData	array	Array of optional additional data, see additionalData
classes	string	Additional classes to add to the key details bar
ariaLabel	string	value for the aria label, this defaults to Key details
attributes	object	HTML Attributes (data attributes) to add to the key details bar

Options for primaryIdentifier object

Name	Type	Description
text	string	Required. Text to use within the primary identifier
value	string	Required. Value to use within the primary identifier

Options for secondaryIdentifier object

Name	Type	Description
text	string	Required. Text to use within the secondary identifier
value	string	Required. Value to use within the secondary identifier

Options for status object

Name	Type	Description
text	string	Required. Text to use within claim status
value	string	Required. Value to use within claim status
classes	string	Additional classes to add to claim status

Options for additionalData array object

Name	Type	Description
text	string	Required. Text to use within each additional data item
value	string	Required. Value to use within each additional data item

{% from "key-details-bar/macro.njk" import dwpKeyDetailsBar %}

{{ 
    dwpKeyDetailsBar({
        primaryIdentifier: {
            text: 'First item description:',
            value: 'First item'
        },
        secondaryIdentifier: {
            text: 'Second item description:',
            value: 'Second item'
        },
        status: {
            text: 'Status description:',
            value: 'Status'
        }
    })
}}

The key details bar is a static display component and should be the same in all views. Do not use different versions of the component in different parts of your service.

How to use the status tag

If your users need to see the status or progress of a case (for example, To do / In progress / Complete), the key details bar can include a status tag with this information. Do not use more than one tag.

If used, the status tag should appear on every record. Do not use it as a flag to show attributes that only apply to some records: this information should be placed somewhere more noticeable than the key details bar.

Changing the tag colour

The default styling for a status tag is blue text on a white background, but you can use the standard tag colours from the GOV.UK Design System if you prefer. Make sure that any colours you use meet accessibility standards for visibility and contrast, and do not use colour alone to show status.

This example shows a tag styled using govuk-tag--green:

Open this example in a new tab

<section class="dwp-key-details-bar" aria-label="Key details">
<div class="dwp-key-details-bar__key-details">
<dl class="dwp-key-details-bar__top-block">
  <dt class="govuk-visually-hidden">Name:</dt>
  <dd class="dwp-key-details-bar__primary">Jane Doe</dd>
  <dt class="govuk-visually-hidden">National Insurance Number:</dt>
  <dd class="dwp-key-details-bar__secondary">QQ 12 34 56 X</dd>
  <dt class="govuk-visually-hidden">Claim status:</dt>
  <dd class="dwp-key-details-bar__status">
    <strong class="govuk-tag govuk-tag--green">
      Active
    </strong>
  </dd>
</dl>
</div>
</section>

Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as “Required” in the option description.

If you’re using Nunjucks macros in production with “html” options, or ones ending with “html”, you must sanitise the HTML to protect against cross-site scripting exploits.

Name	Type	Description
primaryIdentifier	object	Required. The primary identifier, see primaryIdentifier
secondaryIdentifier	object	The secondary identifier, see secondaryIdentifier
status	object	The claim status, see status
additionalData	array	Array of optional additional data, see additionalData
classes	string	Additional classes to add to the key details bar
ariaLabel	string	value for the aria label, this defaults to Key details
attributes	object	HTML Attributes (data attributes) to add to the key details bar

Options for primaryIdentifier object

Name	Type	Description
text	string	Required. Text to use within the primary identifier
value	string	Required. Value to use within the primary identifier

Options for secondaryIdentifier object

Name	Type	Description
text	string	Required. Text to use within the secondary identifier
value	string	Required. Value to use within the secondary identifier

Options for status object

Name	Type	Description
text	string	Required. Text to use within claim status
value	string	Required. Value to use within claim status
classes	string	Additional classes to add to claim status

Options for additionalData array object

Name	Type	Description
text	string	Required. Text to use within each additional data item
value	string	Required. Value to use within each additional data item

{% from "key-details-bar/macro.njk" import dwpKeyDetailsBar %}

{{
    dwpKeyDetailsBar({
        primaryIdentifier: {
            text: 'Name:',
            value: 'Jane Doe'
        },
        secondaryIdentifier: {
            text: 'National Insurance Number:',
            value: 'QQ 12 34 56 X'
        },
        status: {
            text: 'Claim status:',
            value: 'Active',
            classes: 'govuk-tag--green'
        }
    })
}}

Extending the key details bar

The extended key details bar includes a lower block for additional information, separated from the top block by a horizontal rule.

Open this example in a new tab

• Date of birth: 4 June 1972
• Case reference: RM PX 30

<section class="dwp-key-details-bar" aria-label="Key details">
<div class="dwp-key-details-bar__key-details">
<dl class="dwp-key-details-bar__top-block">
  <dt class="govuk-visually-hidden">Name:</dt>
  <dd class="dwp-key-details-bar__primary">Jane Doe</dd>
  <dt class="govuk-visually-hidden">National Insurance Number:</dt>
  <dd class="dwp-key-details-bar__secondary">QQ 12 34 56 X</dd>
  <dt class="govuk-visually-hidden">Claim status:</dt>
  <dd class="dwp-key-details-bar__status">
    <strong class="govuk-tag dwp-key-details-bar__status--dwp-default">
      Completed
    </strong>
  </dd>
</dl>
<dl class="dwp-key-details-bar__bottom-block">
  <dt>Date of birth:</dt>
  <dd>4 June 1972</dd>
  <dt>Case reference:</dt>
  <dd>RM PX 30</dd>
</dl>
</div>
</section>

Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as “Required” in the option description.

If you’re using Nunjucks macros in production with “html” options, or ones ending with “html”, you must sanitise the HTML to protect against cross-site scripting exploits.

Name	Type	Description
primaryIdentifier	object	Required. The primary identifier, see primaryIdentifier
secondaryIdentifier	object	The secondary identifier, see secondaryIdentifier
status	object	The claim status, see status
additionalData	array	Array of optional additional data, see additionalData
classes	string	Additional classes to add to the key details bar
ariaLabel	string	value for the aria label, this defaults to Key details
attributes	object	HTML Attributes (data attributes) to add to the key details bar

Options for primaryIdentifier object

Name	Type	Description
text	string	Required. Text to use within the primary identifier
value	string	Required. Value to use within the primary identifier

Options for secondaryIdentifier object

Name	Type	Description
text	string	Required. Text to use within the secondary identifier
value	string	Required. Value to use within the secondary identifier

Options for status object

Name	Type	Description
text	string	Required. Text to use within claim status
value	string	Required. Value to use within claim status
classes	string	Additional classes to add to claim status

Options for additionalData array object

Name	Type	Description
text	string	Required. Text to use within each additional data item
value	string	Required. Value to use within each additional data item

{% from "key-details-bar/macro.njk" import dwpKeyDetailsBar %}

{{
    dwpKeyDetailsBar({
        primaryIdentifier: {
            text: 'Name:',
            value: 'Jane Doe'
        },
        secondaryIdentifier: {
            text: 'National Insurance Number:',
            value: 'QQ 12 34 56 X'
        },
        status: {
            text: 'Claim status:',
            value: 'Completed'
        },
        additionalData: [
        {
            text: "Date of birth:",
            value: "4 June 1972"
        },
        {
            text: "Case reference:",
            value: "RM PX 30"
        }
        ]
    })
}}

Technical guidance

The key details bar should be placed outside the <main> tag. This will allow a screen reader user to skip past it using the skip link.

You may need your <h1> to reference something from the key details bar so that it still makes sense when a screen reader user skips the bar. This may be required even if your <h1> is visually hidden.

Accessibility

If you include a status tag, take care to check all possible colour combinations for contrast.

For more about building accessible services see the DWP Accessibility Manual.

Research

This component was initially designed to support agents on phone calls who needed confirmation that they were speaking to the right person, and any research insights have been from agent-facing services. We do not have research for this component on public-facing services.

Contribute

If you have used or researched this component, please let us know what you found so we can make it better for everyone. There is an open discussion on GitHub where you can share anything you think might be useful.

Discuss the Key details bar on GitHub

Get in touch

If you’ve got a question, idea or suggestion email the Design System team on dwp-design-system@engineering.digital.dwp.gov.uk