name: Document list description: An ordered list of documents including a document type, when updated and a link. body: | 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 accessibility_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 shared_accessibility_criteria: - link uses_component_wrapper_helper: true examples: default: data: items: - link: text: 'Alternative provision' path: '/government/publications/alternative-provision' metadata: public_updated_at: 2016-06-27 10:29:44 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 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 document_type: 'Statutory guidance' with_margin: description: The component accepts a number for margin bottom from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having a margin bottom of 5 (25px). data: margin_bottom: 9 items: - link: text: 'Alternative provision' path: '/government/publications/alternative-provision' metadata: public_updated_at: 2016-06-27 10:29:44 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 document_type: 'Statutory guidance' without_links: data: items: - link: text: 'Alternative provision' metadata: public_updated_at: 2016-06-27 10:29:44 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 document_type: 'Statutory guidance' - link: text: 'Children missing education' metadata: public_updated_at: 2016-09-05 16:48:27 document_type: 'Statutory guidance' with_data_attributes_on_links: data: 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 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 document_type: 'Statutory guidance' with_description: description: Documents can be passed to the component with a description. This is for use on topic pages, to display lists of mainstream services. data: 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: data: 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 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 document_type: 'Statutory guidance' with_number_10_branding: description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown. data: brand: 'prime-ministers-office-10-downing-street' 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 document_type: 'Statutory guidance' - link: text: 'School exclusion' path: '/government/publications/school-exclusion' metadata: public_updated_at: 2017-07-19 15:01:48 document_type: 'Statutory guidance' with_only_link: data: 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: description: Context can be provided to render next to the item title. data: 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: description: This is used on finders to highlight search results from past governments. data: 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 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 document_type: 'Statistical data set' subtext: 'First published during the 1996 Conservative Government' without_underline: description: The current search design does not include underlines on links and has been tested without underlines. Other uses will require further user testing. data: 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 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 document_type: 'Statistical data set' subtext: 'First published during the 1996 Conservative Government' without_top_border_on_list_element: description: 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. data: 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 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 document_type: 'Statistical data set' without_top_border_on_first_list_element: description: 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. data: 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 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 document_type: 'Statistical data set' with_equal_item_spacing: description: | The new search UI has consistently equal spacing between items in the document list, instead of the original larger bottom padding. data: equal_item_spacing: true 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 - 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.' full_size_description: true - link: text: 'Become enlightened' path: '/become-enlightened' description: 'Becoming enlightened - what to expect, what to take, pay and training, making an application, complaining about being enlightened.' full_size_description: true highlighted_result: description: 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. data: 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 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 document_type: 'Statistical data set' subtext: 'First published during the 1996 Conservative Government' right_to_left: data: 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 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 document_type: 'Organisation' context: right_to_left: true with_parts: description: Display child items, such as parts of guides or travel advice. Child items accept the same parameters as parent items. data: 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_parts_and_no_underline: description: The legacy finders design does not include underlines on links, neither on the main item nor the children. data: remove_underline: true 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: description: | 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang#Language_tag_syntax). 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. data: 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 document_type: 'Data tryloywder' locale: document_type: 'cy' with_full_size_description_text: data: 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: description: | The [rel attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel) 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 data: 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: description: | Allows you to add extra GA4 link tracker attributes, or overwrite the existing ones on the links. See the [ga4-link-tracker documentation](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/ga4-link-tracker.md) for more information. data: ga4_extra_data: hello: 'world' items: - link: text: 'Test link' path: 'https://www.gov.uk' description: "GOV.UK link" without_ga4_tracking: description: | Disables GA4 tracking. Tracking is enabled by default. See the [ga4-link-tracker documentation](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/ga4-link-tracker.md) for more information. data: disable_ga4: true items: - link: text: 'Test link' path: 'https://www.gov.uk' description: "GOV.UK link"