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} />;API reference
CharacterCount.Root
| Prop | Type |
|---|---|
maxLengthThe most characters, or words, the user should enter. Without it there's no count. | number |
countTypeWhat to count: "length" (the default) counts UTF-16 code units, as | CountType |
thresholdThe percentage of the limit from which the count is shown. | number |
charactersUnderLimitTextShown while under the limit. | Translation |
charactersAtLimitTextShown at the limit. | Translation |
charactersOverLimitTextShown while over the limit. | Translation |
wordsUnderLimitTextShown while under the limit when counting words. | Translation |
wordsAtLimitTextShown at the limit when counting words. | Translation |
wordsOverLimitTextShown while over the limit when counting words. | Translation |
hiddenDescriptionClassClasses that visually hide the description once upgraded. Without them, inline styles do. | string |
withinLimitClassClasses for the visible count while within the limit. | string |
overLimitClassClasses for the visible count while over the limit. | string |
belowThresholdClassClasses for the visible count while below | string |
inputOverLimitClassClasses 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.
| Prop | Type |
|---|---|
asChildRender 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.
| Prop | Type |
|---|---|
asChildRender 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.
| Prop | Type |
|---|---|
asChildRender 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.
| Prop | Type |
|---|---|
asChildRender 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.