---
title: Character count (React) - USWDS + Tailwind
description: Show how many characters remain in a limited text field with a
  character count and live feedback.
---

# Character count

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

## Examples

```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.

| Prop | Type | Default | Description |
| - | - | - | - |
| `maxLength` | `number (required)` | `—` | Sets the character limit. Input permits extra characters and becomes invalid when the count exceeds it. |
| `defaultValue` | `string` | `""` | Initial uncontrolled value. |
| `value` | `string` | `—` | Controlled value. |
| `onValueChange` | `({ value: string }) => void` | `—` | Receives value changes. |
| `errorText` | `string` | `"The content is too long."` | Native validity message when over the limit. Defaults to "The content is too long." |
| `statusLabel` | `string` | `"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.

| Attribute | Value | Purpose |
| - | - | - |
| `data-invalid` | `Present when invalid` | Style the error state. |

### Status `<div>`

Displays the remaining-character message.

| Attribute | Value | Purpose |
| - | - | - |
| `data-invalid` | `Present when invalid` | Style the error state. |

### SrStatus `<div>`

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