Search results list
About this pattern
After a user has carried out a site search, you can show a list of search results.
All search results lists must have the following elements:
- results count
- pagination for results over multiple pages
- a ‘no results’ message
The following elements are optional:
- search term spelling suggestions
- related search terms
- ‘sort by’ to help users sort results
The search results list can be unfiltered or you can give the users search filters.
A search results list is made up of individual search results. Read the guidance on creating an individual search result.
Sample HTML
<main class="ds_layout ds_layout--search-results">
<div class="ds_layout__header">
<header class="ds_page-header">
<h1 class="ds_page-header__title">Search</h1>
</header>
</div>
<div class="ds_layout__content">
<div class="ds_site-search">
<form role="search" class="ds_site-search__form">
<label class="ds_label visually-hidden" for="site-search">Search</label>
<div class="ds_input__wrapper ds_input__wrapper--has-icon">
<input name="q" required="" id="site-search" class="ds_input ds_site-search__input" type="search" value="energy efficiency" placeholder="Search" autocomplete="off" />
<button type="submit" class="ds_button js-site-search-button">
<span class="visually-hidden">Search</span>
<svg class="ds_icon" aria-hidden="true" role="img"><use href="/assets/images/icons/icons.stack.svg#search"></use></svg>
</button>
</div>
</form>
</div>
</div>
<div class="ds_layout__list">
<div class="ds_search-results">
<h2 class="ds_search-results__title" aria-live="polite">23,109 results for <span class="ds_search-results__title-query">energy efficiency</span></h2>
<div class="ds_search-controls">
<div class="ds_skip-links ds_skip-links--static">
<ul class="ds_skip-links__list">
<li class="ds_skip-links__item"><a class="ds_skip-links__link" href="#search-results">Skip to results</a></li>
</ul>
</div>
<hr class="ds_search-results__divider">
<form>
<div class="ds_sort-options">
<label class="ds_label" for="sort-by">Sort by</label>
<span class="ds_select-wrapper">
<select class="ds_select" id="sort-by">
<option value="relevance">Most relevant</option>
<option value="date">Updated (newest)</option>
<option value="adate">Updated (oldest)</option>
</select>
<span class="ds_select-arrow" aria-hidden="true"></span>
</span>
<button class="ds_button ds_button--secondary ds_button--small" type="submit">Apply sort</button>
</div>
</form>
</div>
<ol class="ds_search-results__list" data-total="23109" start="1">
<li class="ds_search-result ds_search-result--promoted">
<div class="ds_search-result--promoted-content">
<header class="ds_search-result--promoted-title">Recommended</header>
<h3 class="ds_search-result__title">
<a class="ds_search-result__link" href="#">Energy efficiency</a>
</h3>
<p class="ds_search-result__summary">Actions we are taking to improve <mark>energy</mark> <mark>efficiency</mark> across Scotland.</p>
<dl class="ds_metadata ds_search-result__metadata ds_metadata--inline">
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Format</dt>
<dd class="ds_metadata__value">
Policy
</dd>
</div>
</dl>
</div>
</li>
<li class="ds_search-result">
<h3 class="ds_search-result__title">
<a class="ds_search-result__link" href="#">Home Energy Efficiency Programmes loan scheme: FOI release</a>
</h3>
<p class="ds_search-result__summary">Information request and response under the Freedom of Information (Scotland) Act 2002.</p>
<dl class="ds_search-result__metadata ds_metadata ds_metadata--inline">
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Publication type</dt>
<dd class="ds_metadata__value">
FOI/EIR release
</dd>
</div>
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Date</dt>
<dd class="ds_metadata__value">
12 December 2017
</dd>
</div>
</dl>
</li>
<li class="ds_search-result">
<h3 class="ds_search-result__title">
<a class="ds_search-result__link" href="#">Housing</a>
</h3>
<p class="ds_search-result__summary">All policies, publications, consultations and news relating to housing.</p>
</li>
<li class="ds_search-result">
<h3 class="ds_search-result__title">
<a class="ds_search-result__link" href="#">Energy efficiency funding</a>
</h3>
<p class="ds_search-result__summary">£2 million to help make homes and businesses greener.</p>
<dl class="ds_search-result__metadata ds_metadata ds_metadata--inline">
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Format</dt>
<dd class="ds_metadata__value">
News
</dd>
</div>
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Date</dt>
<dd class="ds_metadata__value">
17 June 2018 00:01
</dd>
</div>
</dl>
</li>
<li class="ds_search-result">
<h3 class="ds_search-result__title">
<a class="ds_search-result__link" href="#">Energy</a>
</h3>
<p class="ds_search-result__summary">All policies, publications, consultations and news relating to <mark>energy</mark>.</p>
</li>
<li class="ds_search-result">
<h3 class="ds_search-result__title">
<a class="ds_search-result__link" href="#">Home energy and fuel poverty</a>
</h3>
<p class="ds_search-result__summary"><mark>Energy</mark> <mark>efficiency</mark> is key to tackling fuel poverty and climate change.</p>
<dl class="ds_metadata ds_search-result__metadata ds_metadata--inline">
<div class="ds_metadata__item">
<dt class="ds_metadata__key visually-hidden">Format</dt>
<dd class="ds_metadata__value">Policy</dd>
</div>
</dl>
</li>
<li class="ds_search-result">
<h3 class="ds_search-result__title">
<a class="ds_search-result__link" href="#">Permanent Secretary</a>
</h3>
<div class="ds_search-result__has-media">
<div class="ds_search-result__media-wrapper">
<div class="ds_search-result__media ds_aspect-box ds_aspect-box--square">
<a class="ds_search-result__media-link" href="#" tabindex="-1">
<img alt="" aria-hidden="true" class="ds_aspect-box__inner" srcset="/binaries/content/gallery/designsystem/examples/jp-marks/96x96-jpg 96w,
/binaries/content/gallery/designsystem/examples/jp-marks/96x96-x2-jpg 192w,
/binaries/content/gallery/designsystem/examples/jp-marks/128x128-jpg 128w,
/binaries/content/gallery/designsystem/examples/jp-marks/128x128-x2-jpg 256w,
/binaries/content/gallery/designsystem/examples/jp-marks/160x160-jpg 160w,
/binaries/content/gallery/designsystem/examples/jp-marks/160x160-x2-jpg 320w" sizes="(min-width: 1200px) 160px,
(min-width: 992px) 128px,
96px" src="/binaries/content/gallery/designsystem/examples/jp-marks/96x96-jpg" loading="lazy" />
</a>
</div>
</div>
<div>
<h4 class="ds_search-result__sub-title">John-Paul Marks</h4>
<p class="ds_search-result__summary">John-Paul Marks was appointed as Permanent Secretary to the Scottish Government on 1 January 2022.</p>
</div>
</div>
</li>
<li class="ds_search-result">
<h3 class="ds_search-result__title">
<a class="ds_search-result__link" href="#">Energy efficiency in homes</a>
</h3>
<p class="ds_search-result__summary">
How we are improving the <mark>energy</mark> <mark>efficiency</mark> of homes in Scotland.
</p>
<dl class="ds_search-result__metadata ds_metadata ds_metadata--inline">
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Format</dt>
<dd class="ds_metadata__value">
Policy
</dd>
</div>
</dl>
<dl class="ds_search-result__context">
<dt class="ds_search-result__context-key">Part of:</dt>
<dd class="ds_search-result__context-value">
<a href="#">Energy efficiency</a>
</dd>
</dl>
</li>
<li class="ds_search-result">
<h3 class="ds_search-result__title">
<a class="ds_search-result__link" href="#">
Industrial energy efficiency
</a>
</h3>
<p class="ds_search-result__summary">
Actions we are taking to improve <mark>energy</mark> <mark>efficiency</mark> within industry.
</p>
<dl class="ds_search-result__metadata ds_metadata ds_metadata--inline">
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Format</dt>
<dd class="ds_metadata__value">
Policy
</dd>
</div>
</dl>
<dl class="ds_search-result__context">
<dt class="ds_search-result__context-key">Part of:</dt>
<dd class="ds_search-result__context-value">
<a href="#">Energy efficiency</a>
</dd>
</dl>
</li>
<li class="ds_search-result">
<h3 class="ds_search-result__title">
<a class="ds_search-result__link" href="#">
Improving energy efficiency
</a>
</h3>
<p class="ds_search-result__summary">
Proposals to make homes warmer and greener.
</p>
<dl class="ds_search-result__metadata ds_metadata ds_metadata--inline">
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Format</dt>
<dd class="ds_metadata__value">
News
</dd>
</div>
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Date</dt>
<dd class="ds_metadata__value">
30 December 2020 10:00
</dd>
</div>
</dl>
</li>
<li class="ds_search-result">
<h3 class="ds_search-result__title">
<a class="ds_search-result__link" href="#">Scottish Industrial Energy Transformation Fund (SIETF)</a>
</h3>
<p class="ds_search-result__summary">Information about the Scottish Industrial <mark>Energy</mark> Transformation Fund (SIETF) which will support manufacturing industries to fund investment-ready <mark>energy</mark> <mark>efficiency</mark> technologies and deeper decarbonisation studies.</p>
<dl class="ds_search-result__metadata ds_metadata ds_metadata--inline">
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Format</dt>
<dd class="ds_metadata__value">
Policy
</dd>
</div>
</dl>
<dl class="ds_search-result__context">
<dt class="ds_search-result__context-key">Part of:</dt>
<dd class="ds_search-result__context-value">
<a href="#">Energy efficiency</a>
</dd>
</dl>
</li>
</ol>
<nav class="ds_pagination" aria-label="Search result pages">
<ul class="ds_pagination__list">
<li class="ds_pagination__item">
<a aria-label="Page 1" aria-current="page" class="ds_pagination__link ds_current" href="#">
<span class="ds_pagination__link-label">1</span>
</a>
</li>
<li class="ds_pagination__item">
<a aria-label="Page 2" class="ds_pagination__link" href="#">
<span class="ds_pagination__link-label">2</span>
</a>
</li>
<li class="ds_pagination__item"">
<a aria-label="Page 3" class="ds_pagination__link" href="#">
<span class="ds_pagination__link-label">3</span>
</a>
</li>
<li class="ds_pagination__item">
<a aria-label="Page 4" class="ds_pagination__link" href="#">
<span class="ds_pagination__link-label">4</span>
</a>
</li>
<li class="ds_pagination__item" aria-hidden="true">
<span class="ds_pagination__link ds_pagination__link--ellipsis">…</span>
</li>
<li class="ds_pagination__item">
<a aria-label="Last page, page 2311" class="ds_pagination__link" href="#">
<span class="ds_pagination__link-label">2311</span>
</a>
</li>
<li class="ds_pagination__item">
<a aria-label="Next page" class="ds_pagination__link ds_pagination__link--text ds_pagination__link--icon" href="#">
<span class="ds_pagination__link-label">Next</span>
<svg class="ds_icon" aria-hidden="true" role="img">
<use href="/assets/images/icons/icons.stack.svg#chevron_right"></use>
</svg>
</a>
</li>
</ul>
</nav>
<aside class="ds_search-results__related" aria-labelledby="search-results__related-title">
<h2 id="search-results__related-title" class="ds_search-results__related-title">Related searches</h2>
<ul class="ds_no-bullets">
<li><a href="#">home energy efficiency</a></li>
<li><a href="#">improving energy efficiency</a></li>
<li><a href="#">Domestic Energy Efficiency</a></li>
<li><a href="#">Energy Efficiency Standard</a></li>
<li><a href="#">Energy Efficiency Programme</a></li>
<li><a href="#">heating and energy efficiency</a></li>
</ul>
</aside>
</div>
</div>
</main>Preparing your content
Before implementing search, you must audit your content to ensure search results are user-focused. This includes:
- cleaning up your content — for example, by removing incorrect or outdated content and ensuring there are no duplicate titles
- identifying missing data that would affect search results — for example, by reviewing search terms through an existing search tool or external search
- cataloguing the data points you have for each piece of content, such as date of publication or topic area — these will dictate the filters, page metadata and sorting options you can provide
Search term spelling suggestions
If a user searches for a term flagged as a misspelling, add the corrected spelling to the search. This may produce more results.
Give the user the option to perform the search again with only the suggested corrected spelling or only their original search term.
Performance data shows that on mygov.scot, users click on the first alternate spelling suggestion around 50% of the time.
Our research shows that there is little value in adding more than 3 suggestions.
Sample HTML
<main class="ds_layout ds_layout--search-results">
<div class="ds_layout__header">
<header class="ds_page-header">
<h1 class="ds_page-header__title">Search</h1>
</header>
</div>
<div class="ds_layout__content">
<div class="ds_site-search">
<form role="search" class="ds_site-search__form">
<label class="ds_label visually-hidden" for="site-search">Search</label>
<div class="ds_input__wrapper ds_input__wrapper--has-icon">
<input name="q" required="" id="site-search" class="ds_input ds_site-search__input" type="search" value="crfting" placeholder="Search" autocomplete="off" />
<button type="submit" class="ds_button js-site-search-button">
<span class="visually-hidden">Search</span>
<svg class="ds_icon" aria-hidden="true" role="img"><use href="/assets/images/icons/icons.stack.svg#search"></use></svg>
</button>
</div>
</form>
</div>
</div>
<div class="ds_layout__list">
<div class="ds_search-results">
<nav class="ds_search-suggestions" aria-label="Alternative search suggestions">
<h2 class="visually-hidden">Also showing results for crofting</h2>
<p>
<span aria-hidden="true">Also showing results for</span> <a aria-label="Show results only for crofting" href="#">crofting</a><br>
<span aria-hidden="true">Show results only for</span> <a aria-label="Show results only for crfting" href="#">crfting</a>
</p>
</nav>
<h2 aria-live="polite" class="ds_search-results__title">3 results for <span class="ds_search-results__title-query">crfting</span> or <span class="ds_search-results__title-query">crofting</span></h2>
<div class="ds_search-controls">
<div class="ds_skip-links ds_skip-links--static">
<ul class="ds_skip-links__list">
<li class="ds_skip-links__item"><a class="ds_skip-links__link" href="#search-results">Skip to results</a></li>
</ul>
</div>
<hr class="ds_search-results__divider">
<form>
<div class="ds_sort-options">
<label class="ds_label" for="sort-by">Sort by</label>
<span class="ds_select-wrapper">
<select class="ds_select" id="sort-by">
<option value="relevance">Most relevant</option>
<option value="date">Updated (newest)</option>
<option value="adate">Updated (oldest)</option>
</select>
<span class="ds_select-arrow" aria-hidden="true"></span>
</span>
<button class="ds_button ds_button--secondary ds_button--small" type="submit">Apply sort</button>
</div>
</form>
</div>
<ol class="ds_search-results__list" data-total="3" start="1">
<li class="ds_search-result">
<h3 class="ds_search-result__title">
<a class="ds_search-result__link" href="#">Agricultural holdings including crofting and small landholdings</a>
</h3>
<p class="ds_search-result__summary">Policy on agricultural holdings, <mark>crofting</mark>, and small landholdings.</p>
<dl class="ds_search-result__metadata ds_metadata ds_metadata--inline">
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Format</dt>
<dd class="ds_metadata__value">
Policy
</dd>
</div>
</dl>
</li>
<li class="ds_search-result">
<h3 class="ds_search-result__title">
<a class="ds_search-result__link" href="#">Consultation on crofting reform</a>
</h3>
<p class="ds_search-result__summary">Public to help shape plans for the reform of <mark>crofting</mark>.</p>
<dl class="ds_search-result__metadata ds_metadata ds_metadata--inline">
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Format</dt>
<dd class="ds_metadata__value">
News
</dd>
</div>
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Date</dt>
<dd class="ds_metadata__value">
28 June 2024 16:30
</dd>
</div>
</dl>
</li>
<li class="ds_search-result">
<h3 class="ds_search-result__title">
<a class="ds_search-result__link" href="#">Crofting Agricultural Grant Scheme (CAGS)</a>
</h3>
<p class="ds_search-result__summary">This plan highlights the core elements necessary to ensure that <mark>crofting</mark> remains at the heart of our rural and remote rural communities.</p>
<dl class="ds_search-result__metadata ds_metadata ds_metadata--inline">
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Publication type</dt>
<dd class="ds_metadata__value">
Strategy/plan
</dd>
</div>
<div class="ds_metadata__item">
<dt class="ds_metadata__key">Date</dt>
<dd class="ds_metadata__value">
18 March 2021
</dd>
</div>
</dl>
<dl class="ds_search-result__context">
<dt class="ds_search-result__context-key">Part of:</dt>
<dd class="ds_search-result__context-value">
<a href="#">Crofting: national development plan</a>
</dd>
</dl>
</li>
</ol>
</div>
</div>
</main>Results count
Show the results count at the top of the list of results. This tells the user:
- where they are within the results count
- the total number of results
- the search terms — both correct and misspelled
Performance data shows users prefer fewer search results. It’s quicker and easier for them to find relevant results. A good internal search tool limits the number of results.
Pagination for results over multiple pages
Split search results over multiple pages if there are more than 10 results. Each page should contain 10 results.
Use the pagination component to enable users to navigate between the pages.
Users choose a page by selecting a page number at the bottom of a search results page, starting at page one. Highlight the page number the user is on.
You can monitor the click-through rate on a search result using the in-built tracking. The click-through rate of search results on mygov.scot shows that:
- over half of users click on the first search result
- 96% of users click on first-page results — they rarely navigate to deeper pages
When using the pagination component within a search results list, some additional changes should be made.
On the first page of results
Show the number of results and the search term — for example, 87 results for [search term].
The attribute data-total, applied to the ds_search-results__list list element, contains the total number of results. It calculates the relative position of each result within the tracking attribute script.
On subsequent result pages
Show the position within the set of results alongside the total number and search term — for example, Showing 21 to 30 of 87 results for [search term].
The additional attribute start, applied to the ds_search-results__list list element, contains the starting position for the current displayed results within the set of results and is by the tracking attribute script.
Sorting search results
Use the ‘sort by’ dropdown to allow users to sort the search results into the order that’s most useful to them.
Put the ‘sort by’ dropdown above the search results.
Examples of sorting options are:
- date of publication
- most relevant
- newest
User research can show the sorting options that are most useful to users.
Only let users sort by an option if that sorting option is across all content. For example, date of publication. Missing data leads to incomplete search results, causing users to miss relevant content.
If the sort is automatically submitted by JavaScript, then add the js-initialised class to the ds_search-results element. This removes the ‘apply sort’ button.
Performance data
Performance data shows that fewer than 5% of search users on gov.scot use the 'sort by' dropdown. Therefore, you should do user testing to find out whether you need to offer users a way to sort results.
By default, you should sort search results in a logical way which may mean you do not need to have a 'sort by' option. Usually, this means sorting by most relevant results first. However, depending on the type of content, your results may be best sorted by publication date.
Related search terms
You can list related searches that may be useful to the user.
Put a list of links at the end of the search results page underneath the pagination. Clicking on a link should start a new search for that search term.
You should limit the number of related search terms to 6 or fewer.
No results message
You should display a no results message if a user has searched for something and there are no results.
The message should:
- clearly explain there are no results to display
- give the user some hints for how to improve their search — for example, by checking the spelling is accurate or searching for something less specific
Sample HTML
<main class="ds_layout ds_layout--search-results">
<div class="ds_layout__header">
<header class="ds_page-header">
<h1 class="ds_page-header__title">Search</h1>
</header>
</div>
<div class="ds_layout__content">
<div class="ds_site-search">
<form role="search" class="ds_site-search__form">
<label class="ds_label visually-hidden" for="site-search">Search</label>
<div class="ds_input__wrapper ds_input__wrapper--has-icon">
<input name="q" required="" id="site-search" class="ds_input ds_site-search__input" type="search" value="xyzuhsdfhbjh" placeholder="Search" autocomplete="off" />
<button type="submit" class="ds_button js-site-search-button">
<span class="visually-hidden">Search</span>
<svg class="ds_icon" aria-hidden="true" role="img"><use href="/assets/images/icons/icons.stack.svg#search"></use></svg>
</button>
</div>
</form>
</div>
</div>
<div class="ds_layout__list">
<section id="search-results" class="ds_search-results" aria-labelledby="search-results__heading">
<h2 class="visually-hidden" id="search-results__heading">Search results</h2>
<div class="ds_no-search-results">
<p><strong>There are no matching results.</strong></p>
<p>Improve your search results by:</p>
<ul>
<li>double-checking your spelling</li>
<li>using fewer keywords</li>
<li>searching for something less specific</li>
</ul>
</div>
</section>
</div>
</main>Website analytics
Many analytics tools offer tracking for site search. The following setup covers more complex tracking to understand:
- which search result users interacted with from a search results page
- how other interactive elements are being used
Tracking interactions with search results
You should track user interactions with search results to understand if internal search engines are providing useful results.
Tracking works through the query being available from the page URL, the click text, click URL and a data attribute showing the result’s position.
Tracking how other interactive elements are used
If a spelling suggestion is provided, you can track clicks to the suggested search terms through the page URL (which contains the original search query), the click text, the click URL and a data attribute.
You can also track:
- interaction with pagination using the data attribute with the number of the results page clicked
- promoted results using the page URL, the click text, click URL and a data attribute showing the result’s position in the list of promoted results
- suggested related search terms through the page URL (which contains the original search query), the click text, the click URL and a data attribute
The data attributes are added automatically by the Design System’s ‘tracking’ script.
If you're using the site search on a single-page app or if it's not possible to put the search query into the URL, you could include the query in the dataLayer for the page.
Accessibility
Suggestions for misspellings use WAI-ARIA attributes to give screen reader users more context. They include:
- overwriting link text with a more descriptive aria-label for each suggestion
- hiding text where it would cause duplication with the links
- wrapping suggestions in a nav element with a descriptive aria-label (supporting evidence: mygov.scot accessibility review, March 2019)
You can implement pagination of search result pages in a way that only refreshes part of the page content, rather than the entire page. To tell users of assistive technology when they’ve changed page, you should:
- apply an aria-live attribute to the heading that describes the total number of results — so if this heading content dynamically changes, the new position in the list of results is announced
- apply focus to the beginning of the content that has been dynamically changed
Evidence
We’ve user tested search filters, search tags and the ‘sort by’ dropdown on gov.scot.
Adding search filters and search tags improved the user experience. Users were able to find the most relevant results.
The ‘sort by’ option also tested well. Users were satisfied they could sort the results in a way that helped them.
Feedback, help and support
If you need help or support you can e-mail us at designsystem@gov.scot
There is a problem
Thanks for your feedback