|
| 1 | +--- |
| 2 | +layout: component |
| 3 | +--- |
| 4 | + |
| 5 | +# Character count |
| 6 | + |
| 7 | +Help users know how much text they can enter when there is a limit on the number of characters. |
| 8 | + |
| 9 | +See the [GOV.UK Design System documentation on character counts](https://design-system.service.gov.uk/components/character-count/) for more information on when to use this component. |
| 10 | + |
| 11 | +```vue-html |
| 12 | +<gv-character-count |
| 13 | + label="Can you provide more detail?" |
| 14 | + :label-is-page-heading="true" |
| 15 | + label-class="govuk-label--l" |
| 16 | + :max-chars="200" |
| 17 | +> |
| 18 | + <template #hint> |
| 19 | + Do not include personal or financial information, like your National Insurance number or credit card details. |
| 20 | + </template> |
| 21 | +</gv-character-count> |
| 22 | +``` |
| 23 | + |
| 24 | +## Counting words instead of characters |
| 25 | + |
| 26 | +Use the `max-words` prop to count words instead of characters. A word is any group of consecutive non-whitespace characters. |
| 27 | + |
| 28 | +```vue-html |
| 29 | +<gv-character-count |
| 30 | + label="Enter a job description" |
| 31 | + :label-is-page-heading="true" |
| 32 | + label-class="govuk-label--l" |
| 33 | + :max-words="150" |
| 34 | +/> |
| 35 | +``` |
| 36 | + |
| 37 | +## Hiding the message until the user is near the limit |
| 38 | + |
| 39 | +You can choose to display a character count message when the length of text within the textarea passes a certain |
| 40 | +‘threshold’ of characters or words. |
| 41 | + |
| 42 | +Use the `threshold` prop to set the threshold. The number you pass will be treated as a percentage - for example, `:threshold="75"` for 75% - and the count |
| 43 | +message will only be shown when the user has entered a length of text that's above that percentage of the limit. |
| 44 | + |
| 45 | +```vue |
| 46 | +<script setup lang="ts"> |
| 47 | +import { ref } from 'vue' |
| 48 | +
|
| 49 | +const text = ref(`This example of a textarea has a character limit of 1000 characters. The character count is hidden, but will appear when more than 850 characters are entered in this textarea. Type some more text into this textarea to see the character count appear. This paragraph will now repeat 2 more times. |
| 50 | +
|
| 51 | +This example of a textarea has a character limit of 1000 characters. The character count is hidden, but will appear when more than 850 characters are entered in this textarea. Type some more text into this textarea to see the character count appear. This paragraph will now repeat 1 more time. |
| 52 | +
|
| 53 | +This example of a textarea has a character limit of 1000 characters. The character count is hidden, but will appear when more than 850 characters are entered in this textarea. Type some more text into this textarea to see the character count appear.`) |
| 54 | +</script> |
| 55 | +
|
| 56 | +<template> |
| 57 | + <gv-character-count |
| 58 | + v-model="text" |
| 59 | + label="Can you provide more detail?" |
| 60 | + :label-is-page-heading="true" |
| 61 | + label-class="govuk-label--l" |
| 62 | + :max-chars="1000" |
| 63 | + :threshold="85" |
| 64 | + /> |
| 65 | +</template> |
| 66 | +``` |
| 67 | + |
| 68 | +## Error messages |
| 69 | + |
| 70 | +You should validate the length of the user's input when they submit the form. If it's over the limit, use the |
| 71 | +`error-message` prop or slot to show a message telling the user what the limit is. The character count message will |
| 72 | +continue to tell them how far over the limit they are. |
| 73 | + |
| 74 | +```vue |
| 75 | +<script setup lang="ts"> |
| 76 | +import { ref } from 'vue' |
| 77 | +
|
| 78 | +const text = ref('A frontend developer designs, builds and improves website software that meets user needs. You will design software which meets user needs and creates meaningful interactions and relationships with users. You will have an understanding of the three fundamental frontend technologies (HTML, CSS and JavaScript). You will create code that is open by default and easy for others to reuse.') |
| 79 | +</script> |
| 80 | +
|
| 81 | +<template> |
| 82 | + <gv-character-count |
| 83 | + v-model="text" |
| 84 | + label="Enter a job description" |
| 85 | + :label-is-page-heading="true" |
| 86 | + label-class="govuk-label--l" |
| 87 | + :max-chars="350" |
| 88 | + error-message="Job description must be 350 characters or less" |
| 89 | + /> |
| 90 | +</template> |
| 91 | +``` |
| 92 | + |
| 93 | +::gvd-options{component="CharacterCount"} |
| 94 | +:: |
0 commit comments