Component

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

Search for usage of this component on GitHub.

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 attribute
  • data_attributes - accepts a hash of data attributes
  • aria - accepts a hash of aria attributes
  • classes - accepts a space separated string of classes, these should not be used for styling and must be prefixed with js-
  • margin_bottom - accepts a number from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale (defaults to no margin)
  • role - accepts a space separated string of roles
  • lang - accepts a language attribute value
  • open - accepts an open attribute value (true or false)
  • hidden - accepts an empty string, ‘hidden’, or ‘until-found’
  • tabindex - accepts an integer. The integer can also be passed as a string.
  • dir - accepts ‘rtl’, ‘ltr’, or ‘auto’.

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"
      }
    }
  ]
} %>

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.

  • Become an apprentice

    Becoming an apprentice - what to expect, apprenticeship levels, pay and training, making an application, complaining about an apprenticeship.

  • Become a journeyman

    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) 

<%= 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 number 10 branding (preview)

Organisation colour branding can be added to the component as shown.

<%= render "govuk_publishing_components/components/document_list", {
  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 +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 context (preview)

Context can be provided to render next to the item title.

<%= 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.

<%= 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.

<%= 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"
      }
    }
  ]
} %>

With equal item spacing (preview)

The new search UI has consistently equal spacing between items in the document list, instead of the original larger bottom padding.

  • Become an apprentice

    Becoming an apprentice - what to expect, apprenticeship levels, pay and training, making an application, complaining about an apprenticeship.

  • Become a journeyman

    Becoming a journeyman - what to expect, what to take, pay and training, making an application, complaining about being a journeyman.

  • Become enlightened

    Becoming enlightened - what to expect, what to take, pay and training, making an application, complaining about being enlightened.

<%= render "govuk_publishing_components/components/document_list", {
  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 (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.

<%= 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) 

<%= 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

    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

<%= 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 parts and no underline (preview)

The legacy finders design does not include underlines on links, neither on the main item nor the children.

  • Universal credit

    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

<%= render "govuk_publishing_components/components/document_list", {
  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 (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)

  • Become an apprentice

    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 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.

<%= 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.

<%= render "govuk_publishing_components/components/document_list", {
  disable_ga4: true,
  items: [
    {
      link: {
        text: "Test link",
        path: "https://www.gov.uk",
        description: "GOV.UK link"
      }
    }
  ]
} %>