Components Quick reference

The quick reference component helps a user to check they are in the right place in a service.

It is intended for use on agent-facing services and case management systems: for example, when an agent needs to check at a glance which case is being displayed.

Name:: Jane Doe
National Insurance number:: QQ 12 34 56 X

<section class="dwp-quick-reference" aria-label="Case information">
<dl class="dwp-quick-reference__block">
<dt class="dwp-quick-reference__label govuk-visually-hidden">Name:</dt>
<dd class="dwp-quick-reference__primary">Jane Doe</dd>
<dt class="dwp-quick-reference__label dwp-quick-reference__label--primary govuk-visually-hidden">National Insurance number:</dt>
<dd class="dwp-quick-reference__secondary">QQ 12 34 56 X</dd>
</dl>
</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
primaryReference	object	Required. The primary reference, see primaryReference
secondaryReference	object	The secondary reference, see secondaryReference
status	object	The claim status, see status
classes	string	Additional classes to add to the quick reference component
ariaLabel	string	value for the aria label, this defaults to Quick reference
attributes	object	HTML Attributes (data attributes) to the quick reference component

Options for primaryReference object

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

Options for secondaryReference object

Name	Type	Description
text	string	Required. Text to use within the secondary reference
textDisplay	boolean	Required. Allow description to be displayed
value	string	Required. Value to use within the secondary reference

Options for status object

Name	Type	Description
text	string	Required. Text to use within claim status
textDisplay	boolean	Allow status description to be displayed
value	string	Required. Value to use within claim status
classes	string	Additional classes to add to claim status

{% from "quick-reference/macro.njk" import dwpQuickReference %}

{{
    dwpQuickReference({
        ariaLabel: "Case information",
        primaryReference: {
            text: 'Name:',
            value: 'Jane Doe'
        },
        secondaryReference: {
            text: 'National Insurance number:',
            value: 'QQ 12 34 56 X'
        }
    })
}}

When to use this component

Use the quick reference component when users need to check they are in the right place when starting or continuing a task. For this purpose it is preferable to the Key details bar, which should not be used in new features or projects.

The intent of the quick reference component is to provide a consistent, static place for reference information that needs to remain visible as the user moves between screens.

It does not have to be at the top of the page, and it does not have to contain personal details or case information.

It is possible to use more than one quick reference component on a page.

Quick reference or Key details bar?

In most cases where you would previously use the Key details bar, you should use the quick reference component instead.

Whereas the key details bar allowed for an optional lower block for more information, the quick reference component does not. It is designed for the specific purpose of showing a minimal amount of unchanging static information so that agents can tell at a glance which record they are working on.

While the standard (unextended) key details bar can be used this way, the quick reference component is:

more flexible and adaptable to different layouts and screen sizes
less prone to the “banner blindness” which can make the key details bar hard to find
more focused on use for reference information, rather than a generic “highlight” feature

If your design uses the extended key details bar as a display panel for high priority information, we recommend:

using the quick reference component for information that helps users check which record they are working on
finding another place for high-priority or important information: the key details bar is unlikely to be the best solution for this

Contact the Design System team for support if you are migrating from the Key details bar to the quick reference component.

When not to use this component

Do not use the quick reference component as a container for the most important information on a page. It is intended to contain the smallest amount of information necessary to tell an agent they are in the right place.

The quick reference component does not work well as banner to draw attention to important or urgent information.

How it works

The quick reference component displays a small amount of information that confirms to the user which record or case is being displayed. Its appearance can be varied but it always:

contains one or two text items of reference information
presents these items in a clear hierarchy
shows the same data items wherever it appears

In its standard form the component includes two text items:

a primary reference
a secondary reference

Name:: Jane Doe
National Insurance number:: QQ 12 34 56 X

<section class="dwp-quick-reference" aria-label="Case information">
<dl class="dwp-quick-reference__block">
<dt class="dwp-quick-reference__label govuk-visually-hidden">Name:</dt>
<dd class="dwp-quick-reference__primary">Jane Doe</dd>
<dt class="dwp-quick-reference__label dwp-quick-reference__label--primary govuk-visually-hidden">National Insurance number:</dt>
<dd class="dwp-quick-reference__secondary">QQ 12 34 56 X</dd>
</dl>
</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
primaryReference	object	Required. The primary reference, see primaryReference
secondaryReference	object	The secondary reference, see secondaryReference
status	object	The claim status, see status
classes	string	Additional classes to add to the quick reference component
ariaLabel	string	value for the aria label, this defaults to Quick reference
attributes	object	HTML Attributes (data attributes) to the quick reference component

Options for primaryReference object

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

Options for secondaryReference object

Name	Type	Description
text	string	Required. Text to use within the secondary reference
textDisplay	boolean	Required. Allow description to be displayed
value	string	Required. Value to use within the secondary reference

Options for status object

Name	Type	Description
text	string	Required. Text to use within claim status
textDisplay	boolean	Allow status description to be displayed
value	string	Required. Value to use within claim status
classes	string	Additional classes to add to claim status

{% from "quick-reference/macro.njk" import dwpQuickReference %}

{{
    dwpQuickReference({
        ariaLabel: "Case information",
        primaryReference: {
            text: 'Name:',
            value: 'Jane Doe'
        },
        secondaryReference: {
            text: 'National Insurance number:',
            value: 'QQ 12 34 56 X'
        }
    })
}}

The references are plain text and should not be interactive. Do not make them links or include tooltips, expanding details or other functionality.

Do not use the same style for both items: there should always be a clear visual hierarchy.

Variations

The component can be used in various layouts and positions: see layout examples in context.

With a status tag

If needed, the component can include a single status tag. This uses the tag component from the GOV.UK Design System.

If you use a coloured tag, make sure all colour options are accessible.

Name:: Jane Doe
National Insurance number:: QQ 12 34 56 X
Claim status:: Active

<section class="dwp-quick-reference" aria-label="Case information">
<dl class="dwp-quick-reference__block">
<dt class="dwp-quick-reference__label govuk-visually-hidden">Name:</dt>
<dd class="dwp-quick-reference__primary">Jane Doe</dd>
<dt class="dwp-quick-reference__label dwp-quick-reference__label--primary govuk-visually-hidden">National Insurance number:</dt>
<dd class="dwp-quick-reference__secondary">QQ 12 34 56 X</dd>
<dt class="dwp-quick-reference__label govuk-visually-hidden">Claim status:</dt>
<dd class="dwp-quick-reference__status">
  <strong class="govuk-tag govuk-tag--green">
    Active
  </strong>
</dd>
</dl>
</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
primaryReference	object	Required. The primary reference, see primaryReference
secondaryReference	object	The secondary reference, see secondaryReference
status	object	The claim status, see status
classes	string	Additional classes to add to the quick reference component
ariaLabel	string	value for the aria label, this defaults to Quick reference
attributes	object	HTML Attributes (data attributes) to the quick reference component

Options for primaryReference object

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

Options for secondaryReference object

Name	Type	Description
text	string	Required. Text to use within the secondary reference
textDisplay	boolean	Required. Allow description to be displayed
value	string	Required. Value to use within the secondary reference

Options for status object

Name	Type	Description
text	string	Required. Text to use within claim status
textDisplay	boolean	Allow status description to be displayed
value	string	Required. Value to use within claim status
classes	string	Additional classes to add to claim status

{% from "quick-reference/macro.njk" import dwpQuickReference %}

{{
    dwpQuickReference({
        ariaLabel: "Case information",
        primaryReference: {
            text: 'Name:',
            value: 'Jane Doe'
        },
        secondaryReference: {
            text: 'National Insurance number:',
            value: 'QQ 12 34 56 X'
        },
        status: {
            text: 'Claim status:',
            value: 'Active',
            classes: 'govuk-tag--green'
        }
    })
}}

Primary reference only

If you do not need the secondary reference you can leave it out.

Name:: Jane Doe

<section class="dwp-quick-reference" aria-label="Citizen information">
<dl class="dwp-quick-reference__block">
<dt class="dwp-quick-reference__label govuk-visually-hidden">Name:</dt>
<dd class="dwp-quick-reference__primary">Jane Doe</dd>
</dl>
</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
primaryReference	object	Required. The primary reference, see primaryReference
secondaryReference	object	The secondary reference, see secondaryReference
status	object	The claim status, see status
classes	string	Additional classes to add to the quick reference component
ariaLabel	string	value for the aria label, this defaults to Quick reference
attributes	object	HTML Attributes (data attributes) to the quick reference component

Options for primaryReference object

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

Options for secondaryReference object

Name	Type	Description
text	string	Required. Text to use within the secondary reference
textDisplay	boolean	Required. Allow description to be displayed
value	string	Required. Value to use within the secondary reference

Options for status object

Name	Type	Description
text	string	Required. Text to use within claim status
textDisplay	boolean	Allow status description to be displayed
value	string	Required. Value to use within claim status
classes	string	Additional classes to add to claim status

{% from "quick-reference/macro.njk" import dwpQuickReference %}

{{
    dwpQuickReference({
        ariaLabel: "Citizen information",
        primaryReference: {
            text: 'Name:',
            value: 'Jane Doe'
        }
    })
}}

With field labels

The secondary reference and status tag (but not the primary reference) can optionally have field labels.

Name:: Jane Doe
National Insurance number:: QQ 12 34 56 X
Claim status:: Active

<section class="dwp-quick-reference" aria-label="Case information">
<dl class="dwp-quick-reference__block">
<dt class="dwp-quick-reference__label govuk-visually-hidden">Name:</dt>
<dd class="dwp-quick-reference__primary">Jane Doe</dd>
<dt class="dwp-quick-reference__label dwp-quick-reference__label--primary">National Insurance number:</dt>
<dd class="dwp-quick-reference__secondary">QQ 12 34 56 X</dd>
<dt class="dwp-quick-reference__label">Claim status:</dt>
<dd class="dwp-quick-reference__status">
  <strong class="govuk-tag govuk-tag--green">
    Active
  </strong>
</dd>
</dl>
</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
primaryReference	object	Required. The primary reference, see primaryReference
secondaryReference	object	The secondary reference, see secondaryReference
status	object	The claim status, see status
classes	string	Additional classes to add to the quick reference component
ariaLabel	string	value for the aria label, this defaults to Quick reference
attributes	object	HTML Attributes (data attributes) to the quick reference component

Options for primaryReference object

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

Options for secondaryReference object

Name	Type	Description
text	string	Required. Text to use within the secondary reference
textDisplay	boolean	Required. Allow description to be displayed
value	string	Required. Value to use within the secondary reference

Options for status object

Name	Type	Description
text	string	Required. Text to use within claim status
textDisplay	boolean	Allow status description to be displayed
value	string	Required. Value to use within claim status
classes	string	Additional classes to add to claim status

{% from "quick-reference/macro.njk" import dwpQuickReference %}

{{
    dwpQuickReference({
        ariaLabel: "Case information",
        primaryReference: {
            text: 'Name:',
            value: 'Jane Doe'
        },
        secondaryReference: {
            text: 'National Insurance number:',
            textDisplay: true,
            value: 'QQ 12 34 56 X'
        },
        status: {
            text: 'Claim status:',
            value: 'Active',
            textDisplay: true,
            classes: 'govuk-tag--green'
        }
    })
}}

Reduced spacing

The spacing can be reduced to make the component smaller:

<section class="dwp-quick-reference dwp-quick-reference--reduced" aria-label="Case information">
<dl class="dwp-quick-reference__block">
<dt class="dwp-quick-reference__label govuk-visually-hidden">Name:</dt>
<dd class="dwp-quick-reference__primary">Jane Doe</dd>
<dt class="dwp-quick-reference__label dwp-quick-reference__label--primary">National Insurance number:</dt>
<dd class="dwp-quick-reference__secondary">QQ 12 34 56 X</dd>
<dt class="dwp-quick-reference__label">Claim status:</dt>
<dd class="dwp-quick-reference__status">
  <strong class="govuk-tag govuk-tag--green">
    Active
  </strong>
</dd>
</dl>
</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
primaryReference	object	Required. The primary reference, see primaryReference
secondaryReference	object	The secondary reference, see secondaryReference
status	object	The claim status, see status
classes	string	Additional classes to add to the quick reference component
ariaLabel	string	value for the aria label, this defaults to Quick reference
attributes	object	HTML Attributes (data attributes) to the quick reference component

Options for primaryReference object

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

Options for secondaryReference object

Name	Type	Description
text	string	Required. Text to use within the secondary reference
textDisplay	boolean	Required. Allow description to be displayed
value	string	Required. Value to use within the secondary reference

Options for status object

Name	Type	Description
text	string	Required. Text to use within claim status
textDisplay	boolean	Allow status description to be displayed
value	string	Required. Value to use within claim status
classes	string	Additional classes to add to claim status

{% from "quick-reference/macro.njk" import dwpQuickReference %}

{{
    dwpQuickReference({
        ariaLabel: "Case information",
        classes: "dwp-quick-reference--reduced",
        primaryReference: {
            text: 'Name:',
            value: 'Jane Doe'
        },
        secondaryReference: {
            text: 'National Insurance number:',
            textDisplay: true,
            value: 'QQ 12 34 56 X'
        },
        status: {
            text: 'Claim status:',
            value: 'Active',
            textDisplay: true,
            classes: 'govuk-tag--green'
        }
    })
}}

White text on blue background

If you are replacing a Key details bar and users find the change in appearance confusing, you can style the component with white text on a blue background for continuity with the earlier version.

Name:: Jane Doe
National Insurance number:: QQ 12 34 56 X

<section class="dwp-quick-reference dwp-quick-reference--alternative" aria-label="Case information">
<dl class="dwp-quick-reference__block">
<dt class="dwp-quick-reference__label govuk-visually-hidden">Name:</dt>
<dd class="dwp-quick-reference__primary">Jane Doe</dd>
<dt class="dwp-quick-reference__label dwp-quick-reference__label--primary">National Insurance number:</dt>
<dd class="dwp-quick-reference__secondary">QQ 12 34 56 X</dd>
</dl>
</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
primaryReference	object	Required. The primary reference, see primaryReference
secondaryReference	object	The secondary reference, see secondaryReference
status	object	The claim status, see status
classes	string	Additional classes to add to the quick reference component
ariaLabel	string	value for the aria label, this defaults to Quick reference
attributes	object	HTML Attributes (data attributes) to the quick reference component

Options for primaryReference object

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

Options for secondaryReference object

Name	Type	Description
text	string	Required. Text to use within the secondary reference
textDisplay	boolean	Required. Allow description to be displayed
value	string	Required. Value to use within the secondary reference

Options for status object

Name	Type	Description
text	string	Required. Text to use within claim status
textDisplay	boolean	Allow status description to be displayed
value	string	Required. Value to use within claim status
classes	string	Additional classes to add to claim status

{% from "quick-reference/macro.njk" import dwpQuickReference %}

{{
    dwpQuickReference({
        ariaLabel: "Case information",
        classes: "dwp-quick-reference--alternative",
        primaryReference: {
            text: 'Name:',
            value: 'Jane Doe'
        },
        secondaryReference: {
            text: 'National Insurance number:',
            textDisplay: true,
            value: 'QQ 12 34 56 X'
        }
    })
}}

Accessibility

If you use status tags, take care to check all possible colour combinations for contrast.

The default ariaLabel is “Quick reference”: you should update this to represent the specific use of the component in your service. The examples on this page use “Case information”.

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

Research

This component is based on the Key details bar, which was designed to support agents on phone calls who needed confirmation that they were speaking to the right person. 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.

For this component we’re particularly interested in hearing about:

schemas other than person name / ID

Discuss Quick reference 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

Cookies on the DWP Design System website

Components Quick reference

Options for primaryReference object

Options for secondaryReference object

Options for status object

When to use this component

Quick reference or Key details bar?

When not to use this component

How it works

Options for primaryReference object

Options for secondaryReference object

Options for status object

Variations

With a status tag

Options for primaryReference object

Options for secondaryReference object

Options for status object

Primary reference only

Options for primaryReference object

Options for secondaryReference object

Options for status object

With field labels

Options for primaryReference object

Options for secondaryReference object

Options for status object

Reduced spacing

Options for primaryReference object

Options for secondaryReference object

Options for status object

White text on blue background

Options for primaryReference object

Options for secondaryReference object

Options for status object

Accessibility

Research

Contribute

Get in touch