Form elements - Character count
Experimental

Help users know how much text they can enter when there is a limit on the number of characters.

Open this default character count example in new window
Copy default character count code 
<div class="nhsuk-character-count" data-module="nhsuk-character-count" data-maxlength="200">

  <div class="nhsuk-form-group">
    <h1 class="nhsuk-label-wrapper">
      <label class="nhsuk-label nhsuk-label--l" for="more-detail">
        Can you provide more detail?
      </label>
    </h1>
    <div class="nhsuk-hint" id="more-detail-hint">
      Do not include personal information like your name, date of birth or NHS number.
    </div>
    <textarea class="nhsuk-textarea nhsuk-js-character-count" id="more-detail" name="more-detail" rows="5" aria-describedby="more-detail-hint"></textarea>
  </div>

  <div class="nhsuk-hint nhsuk-character-count__message" id="more-detail-info">
    You can enter up to 200 characters
  </div>

</div>
Close default character count code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for default character count
Name Type Required Description
Name id Type string Required true Description The id of the textarea.
Name describedBy Type string Required false Description Text or element id to add to the `aria-describedby` attribute to provide description for screenreader users.
Name name Type string Required true Description The name of the textarea, which is submitted with the form data.
Name rows Type string Required false Description Optional number of textarea rows (default is 5 rows).
Name value Type string Required false Description Optional initial value of the textarea.
Name label Type object Required true Description Arguments for the label component. See label component.
Name hint Type object Required false Description Arguments for the hint component (e.g. text). See hint component.
Name errorMessage Type object Required false Description Arguments for the error message component (e.g. text). See error message component.
Name classes Type string Required false Description Optional additional classes to add to the textarea tag. Separate each class with a space.
Name attributes Type object Required false Description Any extra HTML attributes (for example data attributes) to add to the textarea tag.
Name maxlength Type string Required false Description If maxwords is set, this is not required. The maximum number of characters. If maxwords is provided, the maxlength argument will be ignored.
Name maxwords Type string Required false Description If maxlength is set, this is not required. The maximum number of words. If maxwords is provided, the maxlength argument will be ignored.
Name threshold Type string Required false Description The percentage value of the limit at which point the count message is displayed. If this attribute is set, the count message will be hidden by default.
Name countMessage.classes Type string Required false Description Classes to add to the count message.
Copy default character count code 
{% from 'character-count/macro.njk' import characterCount %}

{{ characterCount({
  "name": "more-detail",
  "id": "more-detail",
  "maxlength": 200,
  "label": {
    "text": "Can you provide more detail?",
    "classes": "nhsuk-label--l",
    "isPageHeading": "true"
  },
  "hint": {
    "text": "Do not include personal information like your name, date of birth or NHS number."
  }
}) }}
Close default character count code

When to use character count

Always test your service without a character count first.

Do not use the character count component unless there is a good reason for limiting the number of characters users can enter. For example, if there is:

  • evidence that users are likely to enter more information than they need to
  • a legal or technical reason that means an entry must be no more than a certain number of characters

When not to use character count

If your users keep hitting the character limit imposed by the backend of your service, try to increase the limit rather than use a character count.

How to use character count

How it works

The component tells users how many characters they have remaining as they type into a textarea with a character limit.

Users will get updates at a pace that works best for the way they interact with the textarea. This means:

  • sighted users will see a count message that updates as they type
  • screen reader users will hear the count announcement when they stop typing

This component does not stop the user entering information. The user can enter more than the character limit, but they're told they've entered too many characters. This lets them type or copy and paste their full answer, then edit it down.

The count message appears below the textarea so that:

  • it's clearly separate from any hint text or error message above the textarea
  • if it's below the visible screen area, users will still see it again when they scroll down to send their response

This component uses JavaScript. If JavaScript is not available, users will see a static message in place of the count message, telling them how many characters they can enter.

There are 2 ways to use the character count component. You can use HTML or, if you're using Nunjucks or the NHS.UK Prototype Kit, you can use the Nunjucks macro.

Consider if a word count is more helpful

In some cases it may be more helpful to show a word count. For example, if your question requires a longer answer.

Do this by setting data-maxwords in the component markup. For example, data-maxwords="150" will set a word limit of 150.

Open this word count character count example in new window
Copy word count character count code 
<div class="nhsuk-character-count" data-module="nhsuk-character-count" data-maxwords="150">

  <div class="nhsuk-form-group">
    <label class="nhsuk-label nhsuk-label--l" for="more-detail">
      Enter a job description
    </label>
    <textarea class="nhsuk-textarea nhsuk-js-character-count" id="more-detail" name="more-detail" rows="5"></textarea>
  </div>

  <div class="nhsuk-hint nhsuk-character-count__message" id="more-detail-info">
    You can enter up to 150 words
  </div>

</div>
Close word count character count code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for word count character count
Name Type Required Description
Name id Type string Required true Description The id of the textarea.
Name describedBy Type string Required false Description Text or element id to add to the `aria-describedby` attribute to provide description for screenreader users.
Name name Type string Required true Description The name of the textarea, which is submitted with the form data.
Name rows Type string Required false Description Optional number of textarea rows (default is 5 rows).
Name value Type string Required false Description Optional initial value of the textarea.
Name label Type object Required true Description Arguments for the label component. See label component.
Name hint Type object Required false Description Arguments for the hint component (e.g. text). See hint component.
Name errorMessage Type object Required false Description Arguments for the error message component (e.g. text). See error message component.
Name classes Type string Required false Description Optional additional classes to add to the textarea tag. Separate each class with a space.
Name attributes Type object Required false Description Any extra HTML attributes (for example data attributes) to add to the textarea tag.
Name maxlength Type string Required false Description If maxwords is set, this is not required. The maximum number of characters. If maxwords is provided, the maxlength argument will be ignored.
Name maxwords Type string Required false Description If maxlength is set, this is not required. The maximum number of words. If maxwords is provided, the maxlength argument will be ignored.
Name threshold Type string Required false Description The percentage value of the limit at which point the count message is displayed. If this attribute is set, the count message will be hidden by default.
Name countMessage.classes Type string Required false Description Classes to add to the count message.
Copy word count character count code 
{% from 'character-count/macro.njk' import characterCount %}

{{ characterCount({
  "name": "more-detail",
  "id": "more-detail",
  "maxwords": 150,
  "label": {
    "text": "Enter a job description",
    "classes": "nhsuk-label--l"
  }
}) }}
Close word count character count code

Avoid narrow limits

When using a character count, try to set the limit higher than most users will need. Find out what this is by doing user research and data analysis.

If the limit is much higher than most users are likely to reach, you can choose to only display the message after a user has entered a certain amount.

To do this, set a threshold in the component markup. For example, data-threshold="75" will show the count message only when users have entered 75% of the limit.

Screen reader users will hear the character limit when they first interact with a textarea using the threshold option. Sighted users will not see anything until the count message is shown, though you might choose to include the character limit in the hint text.

Open this threshold character count example in new window
Copy threshold character count code 
<div class="nhsuk-character-count" data-module="nhsuk-character-count" data-maxlength="112" data-threshold="75">

  <div class="nhsuk-form-group">
    <label class="nhsuk-label nhsuk-label--l" for="threshold">
      Can you provide more detail?
    </label>
    <textarea class="nhsuk-textarea nhsuk-js-character-count" id="threshold" name="threshold" rows="5">Type another letter into this field after this message to see the threshold feature</textarea>
  </div>

  <div class="nhsuk-hint nhsuk-character-count__message" id="threshold-info">
    You can enter up to 112 characters
  </div>

</div>
Close threshold character count code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for threshold character count
Name Type Required Description
Name id Type string Required true Description The id of the textarea.
Name describedBy Type string Required false Description Text or element id to add to the `aria-describedby` attribute to provide description for screenreader users.
Name name Type string Required true Description The name of the textarea, which is submitted with the form data.
Name rows Type string Required false Description Optional number of textarea rows (default is 5 rows).
Name value Type string Required false Description Optional initial value of the textarea.
Name label Type object Required true Description Arguments for the label component. See label component.
Name hint Type object Required false Description Arguments for the hint component (e.g. text). See hint component.
Name errorMessage Type object Required false Description Arguments for the error message component (e.g. text). See error message component.
Name classes Type string Required false Description Optional additional classes to add to the textarea tag. Separate each class with a space.
Name attributes Type object Required false Description Any extra HTML attributes (for example data attributes) to add to the textarea tag.
Name maxlength Type string Required false Description If maxwords is set, this is not required. The maximum number of characters. If maxwords is provided, the maxlength argument will be ignored.
Name maxwords Type string Required false Description If maxlength is set, this is not required. The maximum number of words. If maxwords is provided, the maxlength argument will be ignored.
Name threshold Type string Required false Description The percentage value of the limit at which point the count message is displayed. If this attribute is set, the count message will be hidden by default.
Name countMessage.classes Type string Required false Description Classes to add to the count message.
Copy threshold character count code 
{% from 'character-count/macro.njk' import characterCount %}

{{ characterCount({
  "name": "threshold",
  "id": "threshold",
  "maxlength": 112,
  "threshold": 75,
  "value": "Type another letter into this field after this message to see the threshold feature",
  "label": {
    "text": "Can you provide more detail?",
    "classes": "nhsuk-label--l"
  }
}) }}
Close threshold character count code

If you're asking more than 1 question on the page

If you're asking more than 1 question on the page, do not set the contents of the <label> as the page heading. Follow the guidance on asking multiple questions on question pages in the GOV.UK design system.

Open this without heading character count example in new window
Copy without heading character count code 
<div class="nhsuk-character-count" data-module="nhsuk-character-count" data-maxlength="150">

  <div class="nhsuk-form-group">
    <label class="nhsuk-label" for="more-detail">
      Tell us more about what happened.
    </label>
    <textarea class="nhsuk-textarea nhsuk-js-character-count" id="more-detail" name="more-detail" rows="5"></textarea>
  </div>

  <div class="nhsuk-hint nhsuk-character-count__message" id="more-detail-info">
    You can enter up to 150 characters
  </div>

</div>
Close without heading character count code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for without heading character count
Name Type Required Description
Name id Type string Required true Description The id of the textarea.
Name describedBy Type string Required false Description Text or element id to add to the `aria-describedby` attribute to provide description for screenreader users.
Name name Type string Required true Description The name of the textarea, which is submitted with the form data.
Name rows Type string Required false Description Optional number of textarea rows (default is 5 rows).
Name value Type string Required false Description Optional initial value of the textarea.
Name label Type object Required true Description Arguments for the label component. See label component.
Name hint Type object Required false Description Arguments for the hint component (e.g. text). See hint component.
Name errorMessage Type object Required false Description Arguments for the error message component (e.g. text). See error message component.
Name classes Type string Required false Description Optional additional classes to add to the textarea tag. Separate each class with a space.
Name attributes Type object Required false Description Any extra HTML attributes (for example data attributes) to add to the textarea tag.
Name maxlength Type string Required false Description If maxwords is set, this is not required. The maximum number of characters. If maxwords is provided, the maxlength argument will be ignored.
Name maxwords Type string Required false Description If maxlength is set, this is not required. The maximum number of words. If maxwords is provided, the maxlength argument will be ignored.
Name threshold Type string Required false Description The percentage value of the limit at which point the count message is displayed. If this attribute is set, the count message will be hidden by default.
Name countMessage.classes Type string Required false Description Classes to add to the count message.
Copy without heading character count code 
{% from 'character-count/macro.njk' import characterCount %}

{{ characterCount({
  "name": "more-detail",
  "id": "more-detail",
  "maxlength": 150,
  "label": {
    "text": "Tell us more about what happened."
  }
}) }}
Close without heading character count code

Error messages

Error messages should be styled like this.

Open this error character count example in new window
Copy error character count code 
<div class="nhsuk-character-count" data-module="nhsuk-character-count" data-maxlength="350">

  <div class="nhsuk-form-group nhsuk-form-group--error">
    <label class="nhsuk-label nhsuk-label--l" for="exceeding">
      Enter a job description
    </label>
    <div class="nhsuk-hint" id="exceeding-hint">
      Do not include personal information like your name, date of birth or NHS number.
    </div>
    <span class="nhsuk-error-message" id="exceeding-error">
      <span class="nhsuk-u-visually-hidden">Error:</span> Job description must be 350 characters or less
    </span>
    <textarea class="nhsuk-textarea nhsuk-textarea--error nhsuk-js-character-count nhsuk-textarea--error" id="exceeding" name="exceeding-characters" rows="5" aria-describedby="exceeding-hint exceeding-error">A content designer works on the end-to-end journey of a service to help users complete their goal and government deliver a policy intent. Their work may involve the creation of, or change to, a transaction, product or single piece of content that stretches across digital and offline channels. They make sure appropriate content is shown to a user in the right place and in the best format.</textarea>
  </div>

  <div class="nhsuk-hint nhsuk-character-count__message" id="exceeding-info">
    You can enter up to 350 characters
  </div>

</div>
Close error character count code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for error character count
Name Type Required Description
Name id Type string Required true Description The id of the textarea.
Name describedBy Type string Required false Description Text or element id to add to the `aria-describedby` attribute to provide description for screenreader users.
Name name Type string Required true Description The name of the textarea, which is submitted with the form data.
Name rows Type string Required false Description Optional number of textarea rows (default is 5 rows).
Name value Type string Required false Description Optional initial value of the textarea.
Name label Type object Required true Description Arguments for the label component. See label component.
Name hint Type object Required false Description Arguments for the hint component (e.g. text). See hint component.
Name errorMessage Type object Required false Description Arguments for the error message component (e.g. text). See error message component.
Name classes Type string Required false Description Optional additional classes to add to the textarea tag. Separate each class with a space.
Name attributes Type object Required false Description Any extra HTML attributes (for example data attributes) to add to the textarea tag.
Name maxlength Type string Required false Description If maxwords is set, this is not required. The maximum number of characters. If maxwords is provided, the maxlength argument will be ignored.
Name maxwords Type string Required false Description If maxlength is set, this is not required. The maximum number of words. If maxwords is provided, the maxlength argument will be ignored.
Name threshold Type string Required false Description The percentage value of the limit at which point the count message is displayed. If this attribute is set, the count message will be hidden by default.
Name countMessage.classes Type string Required false Description Classes to add to the count message.
Copy error character count code 
{% from 'character-count/macro.njk' import characterCount %}

{{ characterCount({
  "name": "exceeding-characters",
  "id": "exceeding",
  "maxlength": 350,
  "value": "A content designer works on the end-to-end journey of a service to help users complete their goal and government deliver a policy intent. Their work may involve the creation of, or change to, a transaction, product or single piece of content that stretches across digital and offline channels. They make sure appropriate content is shown to a user in the right place and in the best format.",
  "label": {
    "text": "Enter a job description",
    "classes": "nhsuk-label--l"
  },
  "hint": {
    "text": "Do not include personal information like your name, date of birth or NHS number."
  },
  "errorMessage": {
    "text": "Job description must be 350 characters or less"
  }
}) }}
Close error character count code

If a user tries to send their response with too many characters, you must show an error message above the field as well as the count message below it.

The error message tells users what went wrong and how to fix it. The count message provides live feedback and updates as a user types.

The input shows a red border only when the user tries to enter more than the character limit. If the number of characters is within the limit, the input does not show this border even when there's been an error. We felt it might cause the user difficulty if the border disappeared once they started typing.

Make sure errors follow GOV.UK guidance on writing error messages and have specific error messages for specific error states.

If the input is empty

Say "Enter [whatever it is]".

For example, "Enter a summary".

If the input is too long

Say "[whatever it is] must be [number] characters or less".

For example, "Summary must be 400 characters or less".

Research and testing

This component is experimental because we do not yet have enough research with users to be sure of it.

The Government Digital Service (GDS) developed and tested the character count component. Several NHS services are using a character count but we need to know more about how it tests with users.

Known issues and gaps

In Internet Explorer 11, JAWS will ignore any set threshold and announce the character count, even if the user entered less than the threshold.

In Chrome version 99, JAWS will not announce the hint or character count of a pre-populated textarea. This is a known issue for the developer of JAWS (FreedomScientific GitHub issue).

Also, this component counts some characters as multiple characters (GOV.UK GitHub issue). For example, emojis and some non-Latin characters.

Help us improve this guidance

Share insights or feedback and take part in the discussion. We use GitHub as a collaboration space. All the information on it is open to the public.

Feedback or share insights on GitHub

Read more about how to feedback or share insights.

If you have any questions, get in touch with the service manual team.

Updated: April 2023