1. Government Frontend Component Guide
  2. Document list

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. This may include:

  • document title
  • link to the document
  • last updated date object
  • document type

Tracking can be added to the links by supplying optional data attributes for each.

Documents are presented in an ordered list as the component expects that the ordering of the documents is relevant.

Search for usage of this component on GitHub

How it looks (preview all)

  1. Alternative provision
  2. Behaviour and discipline in schools: guide for governing bodies
  3. Children missing education

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-27T10:29:44.000+00:00",
        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-24T16:42:48.000+00:00",
        document_type: "Statutory guidance"
      }
    },
    {
      link: {
        text: "Children missing education",
        path: "/government/publications/children-missing-education"
      },
      metadata: {
        public_updated_at: "2016-09-05T16:48:27.000+00:00",
        document_type: "Statutory guidance"
      }
    }
  ]
} %>

Accessibility acceptance criteria

The component must:

  • inform the user how many items are in the list

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

Other examples

Without links (preview)

  1. Alternative provision
  2. Behaviour and discipline in schools: guide for governing bodies
  3. Children missing education
<%= render "govuk_publishing_components/components/document_list", {
  items: [
    {
      link: {
        text: "Alternative provision"
      },
      metadata: {
        public_updated_at: "2016-06-27T10:29:44.000+00:00",
        document_type: "Statutory guidance"
      }
    },
    {
      link: {
        text: "Behaviour and discipline in schools: guide for governing bodies"
      },
      metadata: {
        public_updated_at: "2015-09-24T16:42:48.000+00:00",
        document_type: "Statutory guidance"
      }
    },
    {
      link: {
        text: "Children missing education"
      },
      metadata: {
        public_updated_at: "2016-09-05T16:48:27.000+00:00",
        document_type: "Statutory guidance"
      }
    }
  ]
} %>

With data attributes on links (preview)

  1. School behaviour and attendance: parental responsibility measures
  2. 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",
        data_attributes: {
          track_category: "navDocumentCollectionLinkClicked",
          track_action: 1.1,
          track_label: "/government/publications/parental-responsibility-measures-for-behaviour-and-attendance",
          track_options: {
            dimension28: 2,
            dimension29: "School behaviour and attendance: parental responsibility measures"
          }
        }
      },
      metadata: {
        public_updated_at: "2017-01-05T14:50:33.000+00:00",
        document_type: "Statutory guidance"
      }
    },
    {
      link: {
        text: "School exclusion",
        path: "/government/publications/school-exclusion",
        data_attributes: {
          track_category: "navDocumentCollectionLinkClicked",
          track_action: 1.2,
          track_label: "/government/publications/school-exclusion",
          track_options: {
            dimension28: 2,
            dimension29: "School exclusion"
          }
        }
      },
      metadata: {
        public_updated_at: "2017-07-19T15:01:48.000+00:00",
        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.

  1. Become an apprentice

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

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

  1. School behaviour and attendance: parental responsibility measures

    The responsibilities parents have relating to school behaviour and attendance.

  2. School exclusion

    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-05T14:50:33.000+00:00",
        document_type: "Statutory guidance"
      }
    },
    {
      link: {
        text: "School exclusion",
        path: "/government/publications/school-exclusion",
        description: "Rules governing school exclusion."
      },
      metadata: {
        public_updated_at: "2017-07-19T15:01:48.000+00:00",
        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.

  1. School behaviour and attendance: parental responsibility measures
  2. School exclusion
<%= 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-05T14:50:33.000+00:00",
        document_type: "Statutory guidance"
      }
    },
    {
      link: {
        text: "School exclusion",
        path: "/government/publications/school-exclusion"
      },
      metadata: {
        public_updated_at: "2017-07-19T15:01:48.000+00:00",
        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.

  1. Forestry Commission separate website
  2. Advisory Committee on the Microbiological Safety of Food 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.

  1. Department for Education – Statistics at DfE

    The Department for Education publishes official statistics on education and children.

    First published during the 2007 Labour Government

  2. State-funded school inspections and outcomes: management information

    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-19T15:01:48.000+00:00",
        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-19T15:01:48.000+00:00",
        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.

  1. Department for Education – Statistics at DfE

    The Department for Education publishes official statistics on education and children.

    First published during the 2007 Labour Government

  2. State-funded school inspections and outcomes: management information

    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-19T15:01:48.000+00:00",
        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-19T15:01:48.000+00:00",
        document_type: "Statistical data set"
      },
      subtext: "First published during the 1996 Conservative Government"
    }
  ]
} %>

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.

  1. Most relevant result

    Department for Education – Statistics at DfE

    The Department for Education publishes official statistics on education and children.

    First published during the 2007 Labour Government

  2. State-funded school inspections and outcomes: management information

    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-19T15:01:48.000+00:00",
        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-19T15:01:48.000+00:00",
        document_type: "Statistical data set"
      },
      subtext: "First published during the 1996 Conservative Government"
    }
  ]
} %>

Right to left (preview)

  1. School behaviour and attendance: parental responsibility measures

    Statutory guidance for schools, local authorities and the police on dealing with poor attendance and behaviour in school

  2. Forestry Commission 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-05T14:50:33.000+00:00",
        document_type: "Statutory guidance"
      }
    },
    {
      link: {
        text: "Forestry Commission",
        path: "/government/organisations/forestry-commission",
        context: "separate website"
      },
      metadata: {
        public_updated_at: "2017-07-19T15:01:48.000+00:00",
        document_type: "Organisation"
      }
    }
  ]
} %>