Document list
An ordered list of documents including a document type, when updated and a link.
Outputs a list to documents, based on an array of document data. A “document” in this context can be an asset (such as a ODT or other downloadable document) or a web page.
The component can display:
- a document title
- a link to the document
- a last updated date object
- a document type
How it looks (preview) (preview all)
How to call this component
<%= render "govuk_publishing_components/components/document_list", {
items: [
{
link: {
text: "Alternative provision",
path: "/government/publications/alternative-provision"
},
metadata: {
public_updated_at: "2016-06-27 10:29:44 +0000",
document_type: "Statutory guidance"
}
},
{
link: {
text: "Behaviour and discipline in schools: guide for governing bodies",
path: "/government/publications/behaviour-and-discipline-in-schools-guidance-for-governing-bodies"
},
metadata: {
public_updated_at: "2015-09-24 16:42:48 +0000",
document_type: "Statutory guidance"
}
},
{
link: {
text: "Children missing education",
path: "/government/publications/children-missing-education"
},
metadata: {
public_updated_at: "2016-09-05 16:48:27 +0000",
document_type: "Statutory guidance"
}
}
]
} %>
Accessibility acceptance criteria
The component must:
- inform the user how many items are in the list
- ensure dashes before each list item are hidden from screen readers
Links in the component must:
- accept focus
- be focusable with a keyboard
- be usable with a keyboard
- indicate when they have focus
- change in appearance when touched (in the touch-down state)
- change in appearance when hovered
- be usable with touch
- be usable with voice commands
- have visible text
- have meaningful text
Other examples
Standard options
This component uses the component wrapper helper. It accepts the following options and applies them to the parent element of the component. See the component wrapper helper documentation for more detail.
id
- accepts a string for the element ID attributedata_attributes
- accepts a hash of data attributesaria
- accepts a hash of aria attributesclasses
- accepts a space separated string of classes, these should not be used for styling and must be prefixed withjs-
role
- accepts a space separated string of roleslang
- accepts a language attribute valueopen
- accepts an open attribute value (true or false)
With margin (preview)
The component accepts a number for margin bottom from 0
to 9
(0px
to 60px
) using the GOV.UK Frontend spacing scale. It defaults to having a margin bottom of 5 (25px).
<%= render "govuk_publishing_components/components/document_list", {
margin_bottom: 9,
items: [
{
link: {
text: "Alternative provision",
path: "/government/publications/alternative-provision"
},
metadata: {
public_updated_at: "2016-06-27 10:29:44 +0000",
document_type: "Statutory guidance"
}
},
{
link: {
text: "Behaviour and discipline in schools: guide for governing bodies",
path: "/government/publications/behaviour-and-discipline-in-schools-guidance-for-governing-bodies"
},
metadata: {
public_updated_at: "2015-09-24 16:42:48 +0000",
document_type: "Statutory guidance"
}
}
]
} %>
Without links (preview)
-
Alternative provision
-
Behaviour and discipline in schools: guide for governing bodies
-
Children missing education
<%= render "govuk_publishing_components/components/document_list", {
items: [
{
link: {
text: "Alternative provision"
},
metadata: {
public_updated_at: "2016-06-27 10:29:44 +0000",
document_type: "Statutory guidance"
}
},
{
link: {
text: "Behaviour and discipline in schools: guide for governing bodies"
},
metadata: {
public_updated_at: "2015-09-24 16:42:48 +0000",
document_type: "Statutory guidance"
}
},
{
link: {
text: "Children missing education"
},
metadata: {
public_updated_at: "2016-09-05 16:48:27 +0000",
document_type: "Statutory guidance"
}
}
]
} %>
With data attributes on links (preview)
<%= render "govuk_publishing_components/components/document_list", {
items: [
{
link: {
text: "School behaviour and attendance: parental responsibility measures",
path: "/government/publications/parental-responsibility-measures-for-behaviour-and-attendance",
data_attributes: {
a_thing: "hello",
another_thing: "there",
more_things: {
look: "over",
there: "now"
}
}
},
metadata: {
public_updated_at: "2017-01-05 14:50:33 +0000",
document_type: "Statutory guidance"
}
},
{
link: {
text: "School exclusion",
path: "/government/publications/school-exclusion",
data_attributes: {
a_thing: "hello",
another_thing: "there",
more_things: {
look: "over",
there: "now"
}
}
},
metadata: {
public_updated_at: "2017-07-19 15:01:48 +0000",
document_type: "Statutory guidance"
}
}
]
} %>
With description (preview)
Documents can be passed to the component with a description. This is for use on topic pages, to display lists of mainstream services.
-
Becoming an apprentice - what to expect, apprenticeship levels, pay and training, making an application, complaining about an apprenticeship.
-
Becoming a journeyman - what to expect, what to take, pay and training, making an application, complaining about being a journeyman.
<%= render "govuk_publishing_components/components/document_list", {
items: [
{
link: {
text: "Become an apprentice",
path: "/become-an-apprentice",
description: "Becoming an apprentice - what to expect, apprenticeship levels, pay and training, making an application, complaining about an apprenticeship."
}
},
{
link: {
text: "Become a journeyman",
path: "/become-a-journeyman",
description: "Becoming a journeyman - what to expect, what to take, pay and training, making an application, complaining about being a journeyman."
}
}
]
} %>
With description and metadata (preview)
-
The responsibilities parents have relating to school behaviour and attendance.
-
Rules governing school exclusion.
<%= render "govuk_publishing_components/components/document_list", {
items: [
{
link: {
text: "School behaviour and attendance: parental responsibility measures",
path: "/government/publications/parental-responsibility-measures-for-behaviour-and-attendance",
description: "The responsibilities parents have relating to school behaviour and attendance."
},
metadata: {
public_updated_at: "2017-01-05 14:50:33 +0000",
document_type: "Statutory guidance"
}
},
{
link: {
text: "School exclusion",
path: "/government/publications/school-exclusion",
description: "Rules governing school exclusion."
},
metadata: {
public_updated_at: "2017-07-19 15:01:48 +0000",
document_type: "Statutory guidance"
}
}
]
} %>
With branding (preview)
Where this component could be used on an organisation page (such as the Attorney General’s Office) branding can be applied for link colours and border colours. See the branding documentation for more details.
<%= render "govuk_publishing_components/components/document_list", {
brand: "attorney-generals-office",
items: [
{
link: {
text: "School behaviour and attendance: parental responsibility measures",
path: "/government/publications/parental-responsibility-measures-for-behaviour-and-attendance"
},
metadata: {
public_updated_at: "2017-01-05 14:50:33 +0000",
document_type: "Statutory guidance"
}
},
{
link: {
text: "School exclusion",
path: "/government/publications/school-exclusion"
},
metadata: {
public_updated_at: "2017-07-19 15:01:48 +0000",
document_type: "Statutory guidance"
}
}
]
} %>
With only link (preview)
<%= render "govuk_publishing_components/components/document_list", {
items: [
{
link: {
text: "School behaviour and attendance: parental responsibility measures",
path: "/government/publications/parental-responsibility-measures-for-behaviour-and-attendance"
}
},
{
link: {
text: "School exclusion",
path: "/government/publications/school-exclusion"
}
}
]
} %>
With context (preview)
Context can be provided to render next to the item title.
- separate website
-
moving to GOV.UK
Works with 4 agencies and public bodies
<%= render "govuk_publishing_components/components/document_list", {
items: [
{
link: {
text: "Forestry Commission",
path: "/government/organisations/forestry-commission",
context: "separate website"
}
},
{
link: {
text: "Advisory Committee on the Microbiological Safety of Food",
path: "/government/organisations/advisory-committee-on-the-microbiological-safety-of-food",
context: "moving to GOV.UK",
description: "Works with 4 agencies and public bodies"
}
}
]
} %>
With subtext (preview)
This is used on finders to highlight search results from past governments.
-
The Department for Education publishes official statistics on education and children.
First published during the 2007 Labour Government
-
Management information published monthly and a one-off publication of inspections and outcomes from 2005 to 2015.
First published during the 1996 Conservative Government
<%= render "govuk_publishing_components/components/document_list", {
items: [
{
link: {
text: "Department for Education – Statistics at DfE",
path: "/government/organisations/department-for-education/about/statistics",
description: "The Department for Education publishes official statistics on education and children."
},
metadata: {
public_updated_at: "2017-07-19 15:01:48 +0000",
document_type: "Corporate information"
},
subtext: "First published during the 2007 Labour Government"
},
{
link: {
text: "State-funded school inspections and outcomes: management information",
path: "/government/organisations/department-for-education/about/statistics",
description: "Management information published monthly and a one-off publication of inspections and outcomes from 2005 to 2015."
},
metadata: {
public_updated_at: "2017-07-19 15:01:48 +0000",
document_type: "Statistical data set"
},
subtext: "First published during the 1996 Conservative Government"
}
]
} %>
Without underline (preview)
The current search design does not include underlines on links and has been tested without underlines. Other uses will require further user testing.
-
The Department for Education publishes official statistics on education and children.
First published during the 2007 Labour Government
-
Management information published monthly and a one-off publication of inspections and outcomes from 2005 to 2015.
First published during the 1996 Conservative Government
<%= render "govuk_publishing_components/components/document_list", {
remove_underline: true,
items: [
{
link: {
text: "Department for Education – Statistics at DfE",
path: "/government/organisations/department-for-education/about/statistics",
description: "The Department for Education publishes official statistics on education and children."
},
metadata: {
public_updated_at: "2017-07-19 15:01:48 +0000",
document_type: "Corporate information"
},
subtext: "First published during the 2007 Labour Government"
},
{
link: {
text: "State-funded school inspections and outcomes: management information",
path: "/government/organisations/department-for-education/about/statistics",
description: "Management information published monthly and a one-off publication of inspections and outcomes from 2005 to 2015."
},
metadata: {
public_updated_at: "2017-07-19 15:01:48 +0000",
document_type: "Statistical data set"
},
subtext: "First published during the 1996 Conservative Government"
}
]
} %>
Without top border on list element (preview)
Several interfaces across GOV.UK benefit from the semantics of the document list but have their own bespoke designs, sometimes meaning that the visual border element doesn’t gel with said interface. Removing it using the below attribute allows for cleaner visual fidelity in these instances.
<%= render "govuk_publishing_components/components/document_list", {
remove_top_border: true,
items: [
{
link: {
text: "Department for Education – Statistics at DfE",
path: "/government/organisations/department-for-education/about/statistics"
},
metadata: {
public_updated_at: "2017-07-19 15:01:48 +0000",
document_type: "Corporate information"
}
},
{
link: {
text: "State-funded school inspections and outcomes: management information",
path: "/government/organisations/department-for-education/about/statistics"
},
metadata: {
public_updated_at: "2017-07-19 15:01:48 +0000",
document_type: "Statistical data set"
}
}
]
} %>
Without top border on first list element (preview)
Several interfaces across GOV.UK benefit from the semantics of the document list but have their own bespoke designs, sometimes meaning that the visual border element doesn’t gel with said interface. Removing it using the below attribute allows for cleaner visual fidelity in these instances.
<%= render "govuk_publishing_components/components/document_list", {
remove_top_border_from_first_child: true,
items: [
{
link: {
text: "Department for Education – Statistics at DfE",
path: "/government/organisations/department-for-education/about/statistics"
},
metadata: {
public_updated_at: "2017-07-19 15:01:48 +0000",
document_type: "Corporate information"
}
},
{
link: {
text: "State-funded school inspections and outcomes: management information",
path: "/government/organisations/department-for-education/about/statistics"
},
metadata: {
public_updated_at: "2017-07-19 15:01:48 +0000",
document_type: "Statistical data set"
}
}
]
} %>
Highlighted result (preview)
Highlight one or more of the items in the list. This is used on finders to provide a ‘top result’ for a search. The highlight_text
parameter is optional.
-
Most relevant result
The Department for Education publishes official statistics on education and children.
First published during the 2007 Labour Government
-
Management information published monthly and a one-off publication of inspections and outcomes from 2005 to 2015.
First published during the 1996 Conservative Government
<%= render "govuk_publishing_components/components/document_list", {
items: [
{
link: {
text: "Department for Education – Statistics at DfE",
path: "/government/organisations/department-for-education/about/statistics",
description: "The Department for Education publishes official statistics on education and children."
},
metadata: {
public_updated_at: "2017-07-19 15:01:48 +0000",
document_type: "Corporate information"
},
subtext: "First published during the 2007 Labour Government",
highlight: true,
highlight_text: "Most relevant result"
},
{
link: {
text: "State-funded school inspections and outcomes: management information",
path: "/government/organisations/department-for-education/about/statistics",
description: "Management information published monthly and a one-off publication of inspections and outcomes from 2005 to 2015."
},
metadata: {
public_updated_at: "2017-07-19 15:01:48 +0000",
document_type: "Statistical data set"
},
subtext: "First published during the 1996 Conservative Government"
}
]
} %>
Right to left (preview)
-
Statutory guidance for schools, local authorities and the police on dealing with poor attendance and behaviour in school
- separate website
<%= render "govuk_publishing_components/components/document_list", {
items: [
{
link: {
text: "School behaviour and attendance: parental responsibility measures",
path: "/government/publications/parental-responsibility-measures-for-behaviour-and-attendance",
description: "Statutory guidance for schools, local authorities and the police on dealing with poor attendance and behaviour in school"
},
metadata: {
public_updated_at: "2017-01-05 14:50:33 +0000",
document_type: "Statutory guidance"
}
},
{
link: {
text: "Forestry Commission",
path: "/government/organisations/forestry-commission",
context: "separate website"
},
metadata: {
public_updated_at: "2017-07-19 15:01:48 +0000",
document_type: "Organisation"
}
}
]
} %>
With parts (preview)
Display child items, such as parts of guides or travel advice. Child items accept the same parameters as parent items.
-
Universal Credit is replacing 6 other benefits with a single monthly payment if you are out of work or on a low income - eligibility, how to prepare
-
What universal credit is
Universal Credit is a payment to help with your living costs. It’s paid monthly - or twice a month for some people in Scotland.
-
Elegibility
You may be able to get Universal Credit if: you’re on a low income or out...
-
Criteria
no url provided, just text
-
What universal credit is
<%= render "govuk_publishing_components/components/document_list", {
items: [
{
link: {
text: "Universal credit",
path: "/universal-credit",
description: "Universal Credit is replacing 6 other benefits with a single monthly payment if you are out of work or on a low income - eligibility, how to prepare"
},
parts: [
{
link: {
text: "What universal credit is",
path: "/universal-credit/what-it-is",
description: "Universal Credit is a payment to help with your living costs. It’s paid monthly - or twice a month for some people in Scotland."
}
},
{
link: {
text: "Elegibility",
path: "/universal-credit/eligibility",
description: "You may be able to get Universal Credit if: you’re on a low income or out...",
data_attributes: {
an_attribute: "some_value"
}
}
},
{
link: {
text: "Criteria",
description: "no url provided, just text"
}
}
]
}
]
} %>
With locale specified (preview)
The component is used on translated pages that don’t have a translation for the document link text or the metadata. This means that it could display the fallback English string if the translate method can’t find an appropriate translation. This makes sure that the lang can be set to ensure that browsers understand which parts of the page are in each language.
Locales can be set separately for the document link text and individual metadata items. To set link text locale, pass a locale attribute along with the link object. To set metadata locale, pass a locale attribute containing a parallel object to your metadata (depending on which metadata have translations and which need a lang attribute to specify that they are in a different language).
The lang attribute must be set to a valid BCP47 string. A valid code can be the two or three letter language code - for example, English is en
or eng
, Korean is ko
or kor
- but if in doubt please check.
<%= render "govuk_publishing_components/components/document_list", {
items: [
{
link: {
text: "Tryloywder Uwch Staff Ysgrifennydd Gwladol Cymru Ionawr-Mawrth 2020",
path: "/government/publications/office-of-the-secretary-of-state-for-wales-senior-staff-transparency-january-march-2020",
locale: "cy"
},
metadata: {
public_updated_at: "2016-06-27 10:29:44 +0000",
document_type: "Data tryloywder",
locale: {
document_type: "cy"
}
}
}
]
} %>
With full size description text (preview)
-
Becoming an apprentice - what to expect, apprenticeship levels, pay and training, making an application, complaining about an apprenticeship.
<%= render "govuk_publishing_components/components/document_list", {
items: [
{
link: {
text: "Become an apprentice",
path: "/become-an-apprentice",
description: "Becoming an apprentice - what to expect, apprenticeship levels, pay and training, making an application, complaining about an apprenticeship.",
full_size_description: true
}
}
]
} %>
With rel link attribute (preview)
The rel attribute is an option attribute to dictate the relationship between the document being linked to and the current page. This is predominantly used by search engines to help index journeys through a website.
On GOV.UK, this is typically used to dictate an external website being linked to with rel="external"
, however this component supports:
- external
- nofollow
- noopener
- noreferrer
- opener
-
Contact Action Fraud to report fraud and cyber crime, or to tell them you've been the victim of a scam.
<%= render "govuk_publishing_components/components/document_list", {
items: [
{
link: {
text: "Report Fraud",
path: "https://www.actionfraud.police.uk/contact-us",
rel: "external",
description: "Contact Action Fraud to report fraud and cyber crime, or to tell them you've been the victim of a scam."
}
}
]
} %>
With extra ga4 data (preview)
Allows you to add extra GA4 link tracker attributes, or overwrite the existing ones on the links. See the ga4-link-tracker documentation for more information.
-
GOV.UK link
<%= render "govuk_publishing_components/components/document_list", {
ga4_extra_data: {
hello: "world"
},
items: [
{
link: {
text: "Test link",
path: "https://www.gov.uk",
description: "GOV.UK link"
}
}
]
} %>
Without ga4 tracking (preview)
Disables GA4 tracking. Tracking is enabled by default. See the ga4-link-tracker documentation for more information.
-
GOV.UK link
<%= render "govuk_publishing_components/components/document_list", {
disable_ga4: true,
items: [
{
link: {
text: "Test link",
path: "https://www.gov.uk",
description: "GOV.UK link"
}
}
]
} %>