Skip to main content

Character count

Show how many characters remain in a limited text field with a character count and live feedback.

Examples

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
You can enter up to 20 characters20 characters allowed
character-count-demo.tsx
import { CharacterCount, Field } from '@uswds-tailwind/react'
export default function CharacterCountDemo() {
return (
<Field.Root className="max-w-xs">
<Field.Label>Text input</Field.Label>
<CharacterCount.Root maxLength={20}>
<CharacterCount.Input />
<CharacterCount.Status />
<CharacterCount.SrStatus />
</CharacterCount.Root>
</Field.Root>
)
}

Component API

Use Root with Input, visible Status, and SrStatus. Use Field.Label inside an enclosing Field.Root to label the input.

Root<div>

Owns the input value and character limit.

PropTypeDefaultDescription
maxLengthnumber (required)—Sets the character limit. Input permits extra characters and becomes invalid when the count exceeds it.
defaultValuestring""Initial uncontrolled value.
valuestring—Controlled value.
onValueChange({ value: string }) => void—Receives value changes.
errorTextstring"The content is too long."Native validity message when over the limit. Defaults to "The content is too long."
statusLabelstring"characters allowed"Text in the initial count message. Defaults to "characters allowed".
ids{ root?: string; control?: string; input?: string; description?: string; status?: string; srStatus?: string }—Overrides generated part IDs. Use Root IDs when a label or external control needs a stable input or trigger target.

Input<input>

Receives text and exposes over-limit state.

AttributeValuePurpose
data-invalidPresent when invalidStyle the error state.

Status<div>

Displays the remaining-character message.

AttributeValuePurpose
data-invalidPresent when invalidStyle the error state.

SrStatus<div>

Renders a div containing the initial limit description and a visually hidden span that announces debounced count changes.