Skip to main content
Primitives

Character count

Tells users how many characters or words they have left as they type.

Used by govuk-react's character count.

Unstyled

The primitive on plain elements, with no GOV.UK markup or styles: what you start from in your own library.

Code
<CharacterCount.Root maxLength={200}>
  <label htmlFor="more-detail">Can you provide more detail?</label>
  <CharacterCount.Input
    id="more-detail"
    name="more-detail"
    rows={5}
    aria-describedby="more-detail-info"
    maxLength={200}
  />
  <CharacterCount.Description id="more-detail-info">You can enter up to 200 characters</CharacterCount.Description>
  <CharacterCount.Status />
  <CharacterCount.ScreenReaderStatus className="visually-hidden" />
</CharacterCount.Root>

In govuk-react

govuk-react's character count, built with this primitive.

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."
/>

Usage

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

<CharacterCount.Root maxLength={200}>
  <label htmlFor="more-detail">Can you provide more detail?</label>
  <CharacterCount.Input id="more-detail" aria-describedby="more-detail-info" maxLength={200} />
  <CharacterCount.Description id="more-detail-info">You can enter up to 200 characters</CharacterCount.Description>
  <CharacterCount.Status />
  <CharacterCount.ScreenReaderStatus className="visually-hidden" />
</CharacterCount.Root>;

Without JavaScript the Description is shown and both statuses are hidden. On upgrade the element visually hides the description, removes the field’s maxlength so users can see by how much they’re over, and shows Status, which updates as the user types. As in govuk-frontend, ScreenReaderStatus updates once the user pauses, rather than on every key, and is hidden from screen readers below threshold.

countType is “length” (the default, as maxlength counts), “characters” (as users see them, such as an emoji as one) or “words”. The messages are English by default, and take a message for each plural form. The statuses get data-state (“under”, “at” or “over”) for styling, or pass class names such as overLimitClass. The field’s value is the state, so a value React sets is counted too.

Inline script

To make the markup interactive before React hydrates, inline @govuk-react/primitives/inline/character-count-element.js, or render it from React on the server:

import { InlineScript, characterCount } from '@govuk-react/primitives/inline-script';

<InlineScript script={characterCount} nonce={nonce} />;

How inline scripts work

API reference

CharacterCount.Root

PropType
maxLength

The most characters, or words, the user should enter. Without it there's no count.

number
countType

What to count: "length" (the default) counts UTF-16 code units, as maxlength does; "characters" counts characters as users see them, such as an emoji as one; "words" counts words.

CountType
threshold

The percentage of the limit from which the count is shown.

number
charactersUnderLimitText

Shown while under the limit. %{count} is the number left.

Translation
charactersAtLimitText

Shown at the limit.

Translation
charactersOverLimitText

Shown while over the limit. %{count} is the number too many.

Translation
wordsUnderLimitText

Shown while under the limit when counting words. %{count} is the number left.

Translation
wordsAtLimitText

Shown at the limit when counting words.

Translation
wordsOverLimitText

Shown while over the limit when counting words. %{count} is the number too many.

Translation
hiddenDescriptionClass

Classes that visually hide the description once upgraded. Without them, inline styles do.

string
withinLimitClass

Classes for the visible count while within the limit.

string
overLimitClass

Classes for the visible count while over the limit.

string
belowThresholdClass

Classes for the visible count while below threshold.

string
inputOverLimitClass

Classes for the field while over the limit.

string

CharacterCount.Description

The description, such as "You can enter up to 200 characters", shown without JavaScript and visually hidden on upgrade. Give it an id and add that to the field's aria-describedby.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

CharacterCount.Input

The field: a textarea, or an input with asChild. Its maxlength is removed on upgrade.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

CharacterCount.ScreenReaderStatus

The count for screen readers, once the user pauses typing. Make it visually hidden.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

CharacterCount.Status

The visible count, hidden from assistive technology. Hidden until the element upgrades.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

CharacterCount.Translation

A message, or one message for each plural form, as in govuk-frontend's localisation.

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