Search
When to use this component
Use the search component when you need users to search for and select a value.
When to not use this component
Do not use the search component as part of a table. In this case, you should use the searchable table component instead.
How it works
Always use the search component as the only component on a page. The search component is often accompanied by a radio component to display the search results, which requires the user to choose an option. If the search and related components are not the only components on the page it is more likely that users will not realise they've missed a question.
Set the contents of the <label> as the page heading. This is good practice as it means that users of screen readers will only hear the contents once.
You will need to include an empty {% title %} block in your web template to override the default page header.
HTML examples
Select the appropriate example from this page and directly integrate the HTML into your web template. You can customise these examples to align with your specific requirements, as indicated below. Refer to the layouts section for further guidance on structuring your web template.
If the component requires submission to a CRM field, ensure to replace the placeholder schema-name text in the HTML example with the actual target field schema name.
Retain any prefixed or suffixed text related to the schema name.
For instance, if the id attribute reads schema-name-hint in the example, ensure the replacement maintains the -hint suffix (e.g. dfe_field-hint).
This step is crucial for allowing the CRM helper framework to validate and submit data to CRM.
Search with hint text
Use hint text for help that's relevant to the majority of users, like how their information will be used, or where to find it. The hint text block is included in the example below.
Hint text is not mandatory, and can be removed if it is not required.
Search with hint text
<div class="govuk-form-group">
<h1 class="govuk-label-wrapper">
<label class="govuk-label govuk-label--l" for="search">
Enter your URN and click the search icon
</label>
</h1>
<div class="govuk-hint" id="search-hint">
If you don't know your URN, you can find it on the Get information about schools (GIAS) service.
</div>
<p id="search-error" class="govuk-error-message govuk-visually-hidden">
<span class="govuk-visually-hidden">Error:</span>
</p>
<div class="dfe-form-search__item-wrapper">
<input class="dfe-form-search__item dfe-form-search__input govuk-!-width-two-thirds" id="search" name="search" title="Search" type="search">
<div class="dfe-form-search__item dfe-form-search__submit-wrapper">
<button class="dfe-form-search__submit" id="search-btn" type="submit">
Search organisation
<svg class="dfe-form-search__icon" width="27" height="27" viewBox="0 0 27 27" fill="none"
xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">
<circle cx="12.0161" cy="11.0161" r="8.51613" stroke="currentColor" stroke-width="3"></circle>
<line x1="17.8668" y1="17.3587" x2="26.4475" y2="25.9393" stroke="currentColor" stroke-width="3"></line>
</svg>
</button>
</div>
</div>
</div>
<div id="search-loader" class="loader govuk-visually-hidden"></div>{% extends 'DfE/Layouts/2ColumnWideLeft' %}
{% block title %}{% endblock %}
{% block main %}
{% unless user %}
<script>
window.location.href="{{ sitemarkers['DfE/Error/AccessDenied'].url }}"
</script>
{% endunless %}
<div class="govuk-form-group">
<h1 class="govuk-label-wrapper">
<label class="govuk-label govuk-label--l" for="search">
Enter your URN and click the search icon
</label>
</h1>
<div class="govuk-hint" id="search-hint">
If you don't know your URN, you can find it on the Get information about schools (GIAS) service.
</div>
<p id="search-error" class="govuk-error-message govuk-visually-hidden">
<span class="govuk-visually-hidden">Error:</span>
</p>
<div class="dfe-form-search__item-wrapper">
<input class="dfe-form-search__item dfe-form-search__input govuk-!-width-two-thirds" id="search" name="search" title="Search" type="search">
<div class="dfe-form-search__item dfe-form-search__submit-wrapper">
<button class="dfe-form-search__submit" id="search-btn" type="submit">
Search organisation
<svg class="dfe-form-search__icon" width="27" height="27" viewBox="0 0 27 27" fill="none"
xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">
<circle cx="12.0161" cy="11.0161" r="8.51613" stroke="currentColor" stroke-width="3"></circle>
<line x1="17.8668" y1="17.3587" x2="26.4475" y2="25.9393" stroke="currentColor" stroke-width="3"></line>
</svg>
</button>
</div>
</div>
</div>
<div id="search-loader" class="loader govuk-visually-hidden"></div>
{% endblock %}Search without hint text
When not to use hint text
Do not use long paragraphs and lists in hint text. Screen readers read out the entire text when users interact with the form element. This could frustrate users if the text is long.
Avoid links in hint text
Do not include links within hint text. While screen readers will read out the link text when describing the field, they will not tell users that the text is a link.
Search without hint text
<div class="govuk-form-group">
<h1 class="govuk-label-wrapper">
<label class="govuk-label govuk-label--l" for="search">
Enter your URN and click the search icon
</label>
</h1>
<p id="search-error" class="govuk-error-message govuk-visually-hidden">
<span class="govuk-visually-hidden">Error:</span>
</p>
<div class="dfe-form-search__item-wrapper">
<input class="dfe-form-search__item dfe-form-search__input govuk-!-width-two-thirds" id="search" name="search" title="Search" type="search">
<div class="dfe-form-search__item dfe-form-search__submit-wrapper">
<button class="dfe-form-search__submit" id="search-btn" type="submit">
Search organisation
<svg class="dfe-form-search__icon" width="27" height="27" viewBox="0 0 27 27" fill="none"
xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">
<circle cx="12.0161" cy="11.0161" r="8.51613" stroke="currentColor" stroke-width="3"></circle>
<line x1="17.8668" y1="17.3587" x2="26.4475" y2="25.9393" stroke="currentColor" stroke-width="3"></line>
</svg>
</button>
</div>
</div>
</div>
<div id="search-loader" class="loader govuk-visually-hidden"></div>{% extends 'DfE/Layouts/2ColumnWideLeft' %}
{% block title %}{% endblock %}
{% block main %}
{% unless user %}
<script>
window.location.href="{{ sitemarkers['DfE/Error/AccessDenied'].url }}"
</script>
{% endunless %}
<div class="govuk-form-group">
<h1 class="govuk-label-wrapper">
<label class="govuk-label govuk-label--l" for="search">
Enter your URN and click the search icon
</label>
</h1>
<p id="search-error" class="govuk-error-message govuk-visually-hidden">
<span class="govuk-visually-hidden">Error:</span>
</p>
<div class="dfe-form-search__item-wrapper">
<input class="dfe-form-search__item dfe-form-search__input govuk-!-width-two-thirds" id="search" name="search" title="Search" type="search">
<div class="dfe-form-search__item dfe-form-search__submit-wrapper">
<button class="dfe-form-search__submit" id="search-btn" type="submit">
Search organisation
<svg class="dfe-form-search__icon" width="27" height="27" viewBox="0 0 27 27" fill="none"
xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">
<circle cx="12.0161" cy="11.0161" r="8.51613" stroke="currentColor" stroke-width="3"></circle>
<line x1="17.8668" y1="17.3587" x2="26.4475" y2="25.9393" stroke="currentColor" stroke-width="3"></line>
</svg>
</button>
</div>
</div>
</div>
<div id="search-loader" class="loader govuk-visually-hidden"></div>
{% endblock %}Error messages
An error message is shown next to the field and in the error summary when there is a validation error. The HTML content for these errors is already included in the component examples and in the base portal web template set up, therefore you do not need to add any additional error containers to your page.
The portal helper framework validation process automatically handles error messages for specific error states.
If nothing is entered
'Enter [whatever it is]'.
For example, 'Enter your URN'.
If the input is too short
'[whatever it is] must be [number] characters or more'.
For example, 'Your reference number must be 8 characters or more'.
If the input is too long
'[whatever it is] must be [number] characters or less'.
For example, 'Your reference must be 8 characters or less'.
If the input has both a minimum and maximum length
'[whatever it is] must be between [number] and [number] characters'.
For example, 'Your reference number must be between 6 and 8 characters'.
If the input has equal value minimum and maximum lengths
'[whatever it is] must be [number] characters'.
For example, 'Your URN must be 6 characters'.
Occasionally you may wish to use error messages outside of the validation process. You can read about the functions available within the portal helper framework to help you with this.
If you would like any additional advice or guidance with using these examples on Power Pages, please contact the Solutions Delivery Team.