Components

Character count

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

<div class="app-example app-example--tabs">
  <div class="app-example__toolbar">
    <a href="/components/character-count/default/index.html" class="app-example__new-window" target="_blank">
      Open this
      <span class="govuk-visually-hidden">character count</span>
      example in a new tab
    </a>
  </div>
  <iframe title="Character count example" data-module="app-example-frame" class="app-example__frame app-example__frame--resizable" src="/components/character-count/default/index.html" frameBorder="0" loading="lazy"></iframe>
</div>

<span id="options-character-count-example"></span>
<ul class="app-tabs" role="tablist">
  <li class="app-tabs__item js-tabs__item" role="presentation"><a href="#character-count-example-html" role="tab" aria-controls="character-count-example-html" data-track="tab-html">HTML</a></li>
  <li class="app-tabs__item js-tabs__item" role="presentation"><a href="#character-count-example-nunjucks" role="tab" aria-controls="character-count-example-nunjucks" data-track="tab-nunjucks">Nunjucks</a></li>
</ul>

  <div class="app-tabs__heading js-tabs__heading"><a href="#character-count-example-html" aria-controls="character-count-example-html" data-track="tab-html">HTML</a></div>

<div class="app-tabs__container js-tabs__container" id="character-count-example-html" role="tabpanel">
  <div class="app-example__code">
    <pre data-module="app-copy" tabindex="0"><code class="hljs html"><span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">&quot;govuk-character-count&quot;</span> <span class="hljs-attr">data-module</span>=<span class="hljs-string">&quot;govuk-character-count&quot;</span> <span class="hljs-attr">data-maxlength</span>=<span class="hljs-string">&quot;200&quot;</span>&gt;</span>

<div class="govuk-form-group"> <h1 class="govuk-label-wrapper"> <label class="govuk-label govuk-label--l" for="with-hint"> Can you provide more detail? </label> </h1> <div id="with-hint-hint" class="govuk-hint"> Do not include personal or financial information like your National Insurance number or credit card details. </div> <textarea class="govuk-textarea govuk-js-character-count" id="with-hint" name="with-hint" rows="5" aria-describedby="with-hint-info with-hint-hint"></textarea> </div> <div id="with-hint-info" class="govuk-hint govuk-character-count__message"> You can enter up to 200 characters </div> </div>

  <div class="app-tabs__heading js-tabs__heading"><a class="app-tabs__heading-link" href="#character-count-example-nunjucks" aria-controls="character-count-example-nunjucks" data-track="tab-nunjucks">Nunjucks</a></div>
<div class="app-tabs__container js-tabs__container" id="character-count-example-nunjucks" role="tabpanel">
    

    <details class="govuk-details app-options" data-module="govuk-details" id="options-character-count-example-details">

Nunjucks macro options

      <p>
      Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
      </p>
      <p>
      Some options are required for the macro to work; these are marked as "Required" in the option description.
      </p>
      <p>
      If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against  <a href="https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting">cross-site scripting exploits</a>.
      </p>
      
        <table class="govuk-table app-options__table" id="options-character-count-example--primary">
          <caption class="govuk-table__caption govuk-heading-m  govuk-visually-hidden">Primary options</caption>
          <thead class="govuk-table__head">
            <tr class="govuk-table__row">
              <th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
              <th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
              <th class="govuk-table__header" scope="col">Description</th>
            </tr>
          </thead>
          <tbody class="govuk-table__body">
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">id</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                    <strong>Required.</strong>
                  
                  The ID of the textarea.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">name</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                    <strong>Required.</strong>
                  
                  The name of the textarea, which is submitted with the form data.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">rows</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                  Optional number of textarea rows (default is 5 rows).
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">value</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                  Optional initial value of the textarea.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">maxlength</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                    <strong>Required.</strong>
                  
                  If <code>maxwords</code> is set, this is not required. The maximum number of characters. If <code>maxwords</code> is provided, the <code>maxlength</code> option will be ignored.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">maxwords</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                    <strong>Required.</strong>
                  
                  If <code>maxlength</code> is set, this is not required. The maximum number of words. If <code>maxwords</code> is provided, the <code>maxlength</code> option will be ignored.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">threshold</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                  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.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">label</th>
                <td class="govuk-table__cell ">object</td>
                <td class="govuk-table__cell ">
                  
                    <strong>Required.</strong>
                  
                  Options for the label component.
                  
                      See <a href="#options-character-count-example--label">label</a>.
                    
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">hint</th>
                <td class="govuk-table__cell ">object</td>
                <td class="govuk-table__cell ">
                  
                  Options for the hint component.
                  
                      See <a href="#options-character-count-example--hint">hint</a>.
                    
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">errorMessage</th>
                <td class="govuk-table__cell ">object</td>
                <td class="govuk-table__cell ">
                  
                  Options for the error message component. The error message component will not display if you use a falsy value for <code>errorMessage</code>, for example <code>false</code> or <code>null</code>.
                  
                      See <a href="/components/error-message/#options-error-message-example">errorMessage</a>.
                    
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">formGroup</th>
                <td class="govuk-table__cell ">object</td>
                <td class="govuk-table__cell ">
                  
                  Options for the form-group wrapper.
                  
                  
                    See <a href="#options-character-count-example--formGroup">formGroup</a>.
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">classes</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                  Classes to add to the textarea.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">attributes</th>
                <td class="govuk-table__cell ">object</td>
                <td class="govuk-table__cell ">
                  
                  HTML attributes (for example data attributes) to add to the textarea.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">spellcheck</th>
                <td class="govuk-table__cell ">boolean</td>
                <td class="govuk-table__cell ">
                  
                  Optional field to enable or disable the <code>spellcheck</code> attribute on the character count.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">countMessage</th>
                <td class="govuk-table__cell ">object</td>
                <td class="govuk-table__cell ">
                  
                  Options for the count message.
                  
                  
                    See <a href="#options-character-count-example--countMessage">countMessage</a>.
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">textareaDescriptionText</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                  Message made available to assistive technologies to describe that the component accepts only a limited amount of content. It is visible on the page when JavaScript is unavailable. The component will replace the <code>%{count}</code> placeholder with the value of the <code>maxlength</code> or <code>maxwords</code> parameter.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">charactersUnderLimitText</th>
                <td class="govuk-table__cell ">object</td>
                <td class="govuk-table__cell ">
                  
                  Message displayed when the number of characters is under the configured maximum, <code>maxlength</code>. This message is displayed visually and through assistive technologies. The component will replace the <code>%{count}</code> placeholder with the number of remaining characters. This is a <a href="https://frontend.design-system.service.gov.uk/localise-govuk-frontend">pluralised list of messages</a>.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">charactersAtLimitText</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                  Message displayed when the number of characters reaches the configured maximum, <code>maxlength</code>. This message is displayed visually and through assistive technologies.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">charactersUnderLimitText</th>
                <td class="govuk-table__cell ">object</td>
                <td class="govuk-table__cell ">
                  
                  Message displayed when the number of characters is over the configured maximum, <code>maxlength</code>. This message is displayed visually and through assistive technologies. The component will replace the <code>%{count}</code> placeholder with the number of characters above the maximum. This is a <a href="https://frontend.design-system.service.gov.uk/localise-govuk-frontend">pluralised list of messages</a>.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">wordsUnderLimitText</th>
                <td class="govuk-table__cell ">object</td>
                <td class="govuk-table__cell ">
                  
                  Message displayed when the number of words is under the configured maximum, <code>maxwords</code>. This message is displayed visually and through assistive technologies. The component will replace the <code>%{count}</code> placeholder with the number of remaining words. This is a <a href="https://frontend.design-system.service.gov.uk/localise-govuk-frontend">pluralised list of messages</a>.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">wordsAtLimitText</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                  Message displayed when the number of words reaches the configured maximum, <code>maxwords</code>. This message is displayed visually and through assistive technologies.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">wordsUnderLimitText</th>
                <td class="govuk-table__cell ">object</td>
                <td class="govuk-table__cell ">
                  
                  Message displayed when the number of words is over the configured maximum, <code>maxwords</code>. This message is displayed visually and through assistive technologies. The component will replace the <code>%{count}</code> placeholder with the number of characters above the maximum. This is a <a href="https://frontend.design-system.service.gov.uk/localise-govuk-frontend">pluralised list of messages</a>.
                  
                  </td>
              </tr>
            
          </tbody>
        </table>
      
        <table class="govuk-table app-options__table" id="options-character-count-example--formGroup">
          <caption class="govuk-table__caption govuk-heading-m ">Options for formGroup</caption>
          <thead class="govuk-table__head">
            <tr class="govuk-table__row">
              <th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
              <th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
              <th class="govuk-table__header" scope="col">Description</th>
            </tr>
          </thead>
          <tbody class="govuk-table__body">
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">classes</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                  Classes to add to the form group (for example to show error state for the whole group).
                  
                  </td>
              </tr>
            
          </tbody>
        </table>
      
        <table class="govuk-table app-options__table" id="options-character-count-example--countMessage">
          <caption class="govuk-table__caption govuk-heading-m ">Options for countMessage</caption>
          <thead class="govuk-table__head">
            <tr class="govuk-table__row">
              <th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
              <th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
              <th class="govuk-table__header" scope="col">Description</th>
            </tr>
          </thead>
          <tbody class="govuk-table__body">
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">classes</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                  Classes to add to the count message.
                  
                  </td>
              </tr>
            
          </tbody>
        </table>
      
        <table class="govuk-table app-options__table" id="options-character-count-example--label">
          <caption class="govuk-table__caption govuk-heading-m ">Options for label</caption>
          <thead class="govuk-table__head">
            <tr class="govuk-table__row">
              <th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
              <th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
              <th class="govuk-table__header" scope="col">Description</th>
            </tr>
          </thead>
          <tbody class="govuk-table__body">
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">text</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                    <strong>Required.</strong>
                  
                  If <code>html</code> is set, this is not required. Text to use within the label. If <code>html</code> is provided, the <code>text</code> option will be ignored.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">html</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                    <strong>Required.</strong>
                  
                  If <code>text</code> is set, this is not required. HTML to use within the label. If <code>html</code> is provided, the <code>text</code> option will be ignored.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">for</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                  The value of the <code>for</code> attribute, the ID of the input the label is associated with.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">isPageHeading</th>
                <td class="govuk-table__cell ">boolean</td>
                <td class="govuk-table__cell ">
                  
                  Whether the label also acts as the heading for the page.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">classes</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                  Classes to add to the label tag.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">attributes</th>
                <td class="govuk-table__cell ">object</td>
                <td class="govuk-table__cell ">
                  
                  HTML attributes (for example data attributes) to add to the label tag.
                  
                  </td>
              </tr>
            
          </tbody>
        </table>
      
        <table class="govuk-table app-options__table" id="options-character-count-example--hint">
          <caption class="govuk-table__caption govuk-heading-m ">Options for hint</caption>
          <thead class="govuk-table__head">
            <tr class="govuk-table__row">
              <th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
              <th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
              <th class="govuk-table__header" scope="col">Description</th>
            </tr>
          </thead>
          <tbody class="govuk-table__body">
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">text</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                    <strong>Required.</strong>
                  
                  If <code>html</code> is set, this is not required. Text to use within the hint. If <code>html</code> is provided, the <code>text</code> option will be ignored.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">html</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                    <strong>Required.</strong>
                  
                  If <code>text</code> is set, this is not required. HTML to use within the hint. If <code>html</code> is provided, the <code>text</code> option will be ignored.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">id</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                  Optional ID attribute to add to the hint span tag.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">classes</th>
                <td class="govuk-table__cell ">string</td>
                <td class="govuk-table__cell ">
                  
                  Classes to add to the hint span tag.
                  
                  </td>
              </tr>
            <tr class="govuk-table__row">
                <th class="govuk-table__header" scope="row">attributes</th>
                <td class="govuk-table__cell ">object</td>
                <td class="govuk-table__cell ">
                  
                  HTML attributes (for example data attributes) to add to the hint span tag.
                  
                  </td>
              </tr>
            
          </tbody>
        </table>

  <div class="app-example__code">
    <pre data-module="app-copy" tabindex="0"><code class="hljs js">{% <span class="hljs-keyword">from</span> <span class="hljs-string">&quot;govuk/components/character-count/macro.njk&quot;</span> <span class="hljs-keyword">import</span> govukCharacterCount %}

{{ govukCharacterCount({ name: "with-hint", id: "with-hint", maxlength: 200, label: { text: "Can you provide more detail?", classes: "govuk-label--l", isPageHeading: true }, hint: { text: "Do not include personal or financial information like your National Insurance number or credit card details." } }) }}