@dwp/govuk-casa/views/casa/components/character-count/README.md

A framework for building GOVUK Collect-And-Submit-Applications

# Character Count

Extends the [`govukCharacterCount()`](https://design-system.service.gov.uk/components/character-count/) macro.

Custom parameters:

- `casaErrors` - form errors (just pass `formErrors`)

## Example usage

Basic example:

```nunjucks
{% from "casa/components/character-count/macro.njk" import casaGovukCharacterCount with context %}

casaGovukCharacterCount({
  name: "name",
  value: formData.name,
  casaErrors: formErrors
})
```

## Google Tag Manager

The following attributes will be attached to the error `<p>` tag if `casaWithAnalytics` is `true`:

- `data-ga-question`: Holds the fieldset label's text content

These are the conventions used by DWP.

> **IMPORTANT:** DO NOT ENABLE this option if the question or answer may contain personally-identifiable information as values will be pushed to Google

## Translations

CASA includes English and Welsh for the character and word count default content according to the [GOV.UK pluralisation rules](https://frontend.design-system.service.gov.uk/localise-govuk-frontend/#understanding-pluralisation-rules), but you can provide further translations or override the messages by adding the following keys to your `common.json` locale file:

```json
{
  "characterCount": {
    "characters": {
      "description": "You can enter up to %{count} characters",
      "underLimitOne": "You have 1 character remaining",
      "underLimitTwo": "You have 2 characters remaining",
      "underLimitFew": "You have 3 characters remaining",
      "underLimitMany": "You have %{count} characters remaining",
      "underLimitOther": "You have %{count} characters remaining",
      "atLimit": "You have 0 characters remaining",
      "overLimitOne": "You have 1 character too many",
      "overLimitTwo": "You have 2 characters too many",
      "overLimitFew": "You have 3 characters too many",
      "overLimitMany": "You have %{count} characters too many",
      "overLimitOther": "You have %{count} characters too many"
    },
    "words": {
      "description": "You can enter up to %{count} words",
      "underLimitOne": "You have 1 word remaining",
      "underLimitTwo": "You have 2 words remaining",
      "underLimitFew": "You have 3 words remaining",
      "underLimitMany": "You have %{count} words remaining",
      "underLimitOther": "You have %{count} words remaining",
      "atLimit": "You have 0 words remaining",
      "overLimitOne": "You have 1 word too many",
      "overLimitTwo": "You have 2 words too many",
      "overLimitFew": "You have 3 words too many",
      "overLimitMany": "You have %{count} words too many",
      "overLimitOther": "You have %{count} words too many"
    }
  }
}
```

The character count message content can also be overridden on a per component basis using the `textareaDescriptionText`, `charactersUnderLimitText`, `charactersAtLimitText`, `charactersOverLimitText`, `wordsUnderLimitText`, `wordsAtLimitText`, and `wordsOverLimitText` parameters.

For example:

```jinja
{% from "govuk/components/character-count/macro.njk" import govukCharacterCount %}

{{ casaGovukCharacterCount({
  maxlength: 200,
  label: {
    text: "Can you provide more detail?",
    classes: "govuk-label--l",
    isPageHeading: true
  },
  charactersOverLimitText: {
    one: "1 character too many",
    other: "${count} characters too many"
  },
}) }}
```

For more information see the [Character Count GOV.UK Design System page](https://design-system.service.gov.uk/components/character-count/).