Skip to main content
Components

Character count

Help users know how much text they can enter when there is a limit on the number of characters. The count appears when JavaScript runs; without it, the field shows how much users can enter.

Read the Design System guidance for character count

Import

import * as CharacterCount from 'govuk-react/character-count';

Examples

Default

Code
<CharacterCount.Field
  id="with-hint"
  name="withHint"
  maxLength={200}
  label="Can you provide more detail?"
  labelSize="l"
  labelIsPageHeading
  hint="Do not include personal or financial information like your National Insurance number or credit card details."
/>

Counting words

Code
<CharacterCount.Field
  id="with-word-count"
  name="withWordCount"
  countType="words"
  maxLength={150}
  label="Enter a job description"
  labelSize="l"
  labelIsPageHeading
/>

With threshold

Code
<CharacterCount.Field
  id="threshold"
  name="threshold"
  maxLength={112}
  threshold={75}
  label="Can you provide more detail?"
  labelSize="l"
  labelIsPageHeading
  defaultValue="Type another letter into this field after this message to see the threshold feature"
/>

Over the limit

Over the limit, as users see it once they've typed too much.

Code
<CharacterCount.Field
  id="exceeding-characters"
  name="exceedingCharacters"
  maxLength={350}
  label="Enter a job description"
  labelSize="l"
  labelIsPageHeading
  defaultValue={jobDescription}
/>

With error message

Code
<CharacterCount.Field
  id="with-error"
  name="withError"
  maxLength={350}
  label="Enter a job description"
  labelSize="l"
  labelIsPageHeading
  errorMessage="Job description must be 350 characters or less"
  defaultValue={jobDescription}
/>

With parts

Code
<CharacterCount.Root maxLength={200}>
  <Label htmlFor="with-parts">Can you provide more detail?</Label>
  <CharacterCount.Textarea id="with-parts" name="withParts" aria-describedby="with-parts-info" />
  <CharacterCount.Message id="with-parts-info">You can enter up to 200 characters</CharacterCount.Message>
  <CharacterCount.Status />
  <CharacterCount.ScreenReaderStatus />
</CharacterCount.Root>

API reference

CharacterCount.Root

Tell users how many characters or words they can enter into a textarea.

Wrap Textarea, Message, Status and ScreenReaderStatus, with the label, hint and error message.

PropType
errorboolean
maxLength

The maximum number of characters (or words if countType is set to "words").

number
maxWords

The maximum number of words. Replaced by the maxLength and countType: "words" options.

number
threshold

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.

number
countType

The count type used to count the text – "length" or "words". Defaults to "length".

"words" | "characters" | "length"
textareaDescriptionText

Message made available to assistive technologies to describe that the component accepts only a limited amount of content. It is visible on the page if countType is not supported or JavaScript is unavailable. The component will replace the %{count} placeholder with the value of the maxLength parameter.

string
charactersUnderLimitText

Message displayed when the number of characters is under the configured maximum, maxLength. This message is displayed visually and through assistive technologies. The component will replace the %{count} placeholder with the number of remaining characters. Our pluralisation rules apply to this macro option.

Translation
charactersAtLimitText

Message displayed when the number of characters reaches the configured maximum, maxLength. This message is displayed visually and through assistive technologies.

string
charactersOverLimitText

Message displayed when the number of characters is over the configured maximum, maxLength. This message is displayed visually and through assistive technologies. The component will replace the %{count} placeholder with the number of characters above the maximum. Our pluralisation rules apply to this macro option.

Translation
wordsUnderLimitText

Message displayed when the number of words is under the configured maximum, maxLength with countType: "words". This message is displayed visually and through assistive technologies. The component will replace the %{count} placeholder with the number of remaining words. Our pluralisation rules apply to this macro option.

Translation
wordsAtLimitText

Message displayed when the number of words reaches the configured maximum, maxLength with countType: "words". This message is displayed visually and through assistive technologies.

string
wordsOverLimitText

Message displayed when the number of words is over the configured maximum, maxLength with countType: "words". This message is displayed visually and through assistive technologies. The component will replace the %{count} placeholder with the number of words above the maximum. Our pluralisation rules apply to this macro option.

Translation

CharacterCount.Field

Tell users how many characters or words they can enter into a textarea.

PropType
labelSize"s" | "m" | "l" | "xl"
labelIsPageHeadingboolean
widthFluidWidth
maxLength

The maximum number of characters (or words if countType is set to "words").

number
maxWords

The maximum number of words. Replaced by the maxLength and countType: "words" options.

number
threshold

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.

number
countType

The count type used to count the text – "length" or "words". Defaults to "length".

"words" | "characters" | "length"
textareaDescriptionText

Message made available to assistive technologies to describe that the component accepts only a limited amount of content. It is visible on the page if countType is not supported or JavaScript is unavailable. The component will replace the %{count} placeholder with the value of the maxLength parameter.

string
charactersUnderLimitText

Message displayed when the number of characters is under the configured maximum, maxLength. This message is displayed visually and through assistive technologies. The component will replace the %{count} placeholder with the number of remaining characters. Our pluralisation rules apply to this macro option.

Translation
charactersAtLimitText

Message displayed when the number of characters reaches the configured maximum, maxLength. This message is displayed visually and through assistive technologies.

string
charactersOverLimitText

Message displayed when the number of characters is over the configured maximum, maxLength. This message is displayed visually and through assistive technologies. The component will replace the %{count} placeholder with the number of characters above the maximum. Our pluralisation rules apply to this macro option.

Translation
wordsUnderLimitText

Message displayed when the number of words is under the configured maximum, maxLength with countType: "words". This message is displayed visually and through assistive technologies. The component will replace the %{count} placeholder with the number of remaining words. Our pluralisation rules apply to this macro option.

Translation
wordsAtLimitText

Message displayed when the number of words reaches the configured maximum, maxLength with countType: "words". This message is displayed visually and through assistive technologies.

string
wordsOverLimitText

Message displayed when the number of words is over the configured maximum, maxLength with countType: "words". This message is displayed visually and through assistive technologies. The component will replace the %{count} placeholder with the number of words above the maximum. Our pluralisation rules apply to this macro option.

Translation
label

The label used by the character count component.

ReactNode
hint

Can be used to add a hint to the character count component.

ReactNode
errorMessage

Can be used to add an error message to the character count component. The error message component will not display if you use a falsy value for errorMessage, for example false or null.

ReactNode

CharacterCount.Message

The description, such as "You can enter up to 200 characters". Shown without JavaScript, and visually hidden once the count shows. Give it the field's id followed by -info, and add that to the field's aria-describedby.

No props of its own. Other props are passed to the element it renders.

CharacterCount.ScreenReaderStatus

The count for screen readers, after Status, once the user pauses typing.

No props of its own. Other props are passed to the element it renders.

CharacterCount.Status

The visible count, after Message. Shown once JavaScript runs.

No props of its own. Other props are passed to the element it renders.

CharacterCount.Textarea

The field.

PropType
errorboolean
widthFluidWidth