CivicTheme
  • Docs
  • Changelog
  • Getting started
    • Introduction
    • Installation
    • Getting help
    • Security policy
    • Partnerships
  • Installation
    • Drupal theme
  • Contributing
    • Contribution model
    • Contribution basics
    • Small contribution spec
    • Medium contribution spec
    • Major (RFC-level) contribution spec
    • Code of conduct
    • Figma contributions
  • Components
    • Component list
    • Atoms
      • Button
      • Chip
      • Content link
      • Check box
      • Field description
      • Field message
      • Fieldset
      • Label
      • Radio
      • Select
      • Textarea
      • Text field
      • Heading
      • Link
      • Paragraph
      • Popover
      • Quote
      • Table
      • Tag
      • Text list
    • Molecules
      • Accordion
      • Attachment
      • Breadcrumb
      • Callout
      • Event Card
      • Field
      • Figure
      • Group filter
      • Logo
      • Map
      • Navigation card
      • Next step
      • Pagination
      • Promo card
      • Search
      • Service card
      • Single filter
      • Snippet
      • Subject Card
      • Table of Contents
      • Tabs
      • Tag List
      • Tooltip
      • Video Player
    • Organisms
      • Alert
      • Banner
      • Campaign
      • Footer
      • Header
      • List
      • Message
      • Mobile Navigation
      • Navigation
      • Promo
      • Side Navigation
      • Skip link
      • Slider
      • Social links
  • Content Authoring
    • Overview
    • Global settings
      • Favicon
      • Header
        • Site slogan
        • Header logos
        • Primary navigation
        • Secondary navigation
      • Banner
      • Search
      • Link
      • Skip link
      • Side navigation
      • Signup
      • Footer
        • Footer logo
        • Social links
        • Footer navigation
        • Acknowledgement of Country
        • Copyright
      • Colours
    • Content types
      • Page
        • Configure the banner
      • Event
      • Alert
    • Content components
      • Accordion
      • Automated list
      • Attachment
      • Callout
      • Campaign
      • Content
        • Quote
      • iFrame
      • Manual List
        • Event card
        • Event reference card
        • Navigation card
        • Navigation reference card
        • Promo card
        • Promo reference card
        • Publication card
        • Service card
        • Subject card
        • Subject reference card
        • Snippet
      • Map
      • Next step
      • Promo
      • Slider
      • Webform
    • Vocabularies
      • Topics
      • Site sections
    • User accounts & roles
Powered by GitBook
On this page
  • When to use
  • When not to use
  • Best practice guidelines
  • Variations
  • Accessibility
  • Security
  • Component inspiration and uplift
  • User research on this component
  • Known issues
  • More research needed
  • Help improve this component
  • Resources
  • References
  • Changelog
  • Contact us

Was this helpful?

Edit on GitHub
Export as PDF
  1. Components
  2. Atoms

Textarea

The Textarea component is a multi-line text input field that allows users to enter longer forms of text data such as comments, reviews, or descriptions.

When to use

Use the Textarea component when:

  • Users need to enter multiple lines of text

  • The expected input requires more space than a standard text field

  • Users need to provide detailed information, such as comments, feedback, descriptions, or biographical information

  • The form requires flexible-length content that may vary significantly in length between users

When not to use

Do not use the Textarea component when:

  • Users only need to enter a single line of text (use a Textfield component instead)

  • The input is structured data with a specific format, such as dates, phone numbers, or postcodes

  • The expected input is very large (consider a file upload option instead)

  • The content is sensitive and needs to be masked (use a password field instead)


Best practice guidelines

  • Clear labelling: Always include a clear, descriptive label that indicates what information is expected.

  • Appropriate sizing: Set an appropriate initial size for the textarea based on the expected length of content to reduce the need for scrolling.

  • Resize functionality: Allow users to resize the textarea to accommodate their content needs, but consider setting minimum and maximum sizes.

  • Character counters: Include character counters when there are minimum or maximum length requirements.

  • Responsive design: Ensure the textarea resizes appropriately across different screen sizes and devices.

  • Error handling: Provide clear error messages when validation fails (such as minimum length requirements, required fields).

  • Placeholder text: Use placeholder text sparingly and only to provide additional context, not to replace labels.

  • Focus states: Ensure the textarea has clear focus states to support keyboard navigation.

  • Validation timing: Consider when to validate the textarea content—on submit, on blur, or as the user types.

  • Default values: Pre-populate textareas with default values only when it would help users complete the task more efficiently.

Variations

  • Default: Standard textarea with no pre-filled content

  • With placeholder text: Textarea with light grey text indicating the expected input format

  • With default value: Textarea pre-populated with content that users can edit

  • Invalid state: Textarea with validation error styling

  • Disabled state: Textarea that cannot be interacted with

  • Resizable/Non-resizable: Controls whether users can manually resize the field

  • Fixed height/Auto-expanding: Controls whether the textarea grows with content or uses scrollbars


Accessibility

According to the 'CivicTheme v1.7.0 Accessibility Assessments' file, the Textarea component has been tested against WCAG 2.2 standards with the following results:

The Textarea component meets WCAG 2.2 compliance requirements, with specific tests for:

WCAG Criterion
Level
Status

1.3.1 Info and Relationships

A

Pass

1.3.5 Identify Input Purpose

AA

Pass

1.4.4 Resize text

AA

Pass

1.4.12 Text Spacing

AA

Pass

2.1.1 Keyboard

A

Pass

2.1.2 No Keyboard Trap

A

Pass

2.4.3 Focus Order

A

Pass

2.4.7 Focus Visible

AA

Pass

2.5.3 Label in Name

A

Pass

2.5.8 Target Size (Minimum)

AA

Fail

3.2.1 On Focus

A

Pass

3.2.2 On Input

A

Pass

3.3.2 Labels or Instructions

A

Pass

3.3.3 Error Suggestion

AA

Pass

4.1.2 Name, Role, Value

A

Pass

4.1.3 Status Messages

AA

Pass

Note: The component fails the 2.5.8 Target Size (Minimum) criterion, which requires interaction targets to be at least 24 by 24 CSS pixels.

Security

When implementing the Textarea component, consider the following security considerations:

  • Implement proper input sanitization to prevent cross-site scripting (XSS) attacks

  • Set appropriate character limits to prevent buffer overflow attacks

  • Apply timeout features for forms containing sensitive information

  • Ensure data submitted through textareas is properly validated server-side

These security considerations align with the requirements outlined in the Policy for the responsible use of AI in government v1.1, which emphasizes the importance of protecting user data when collecting input.

Component inspiration and uplift

This component has been modelled after the Text input component in the Australian Government Design System (AGDS). It has been uplifted by Salsa Digital, as the custodian of the CivicTheme Design System, in the following ways:

  • CivicTheme's Textarea input field is presented with a thinner, 1px border for a cleaner look, while maintaining accessibility

  • The component displays an additional interactive hover state with a 2px border (similar to ADS' default style)

  • The handles for resizing the input are more prominent

  • The Invalid inputs use new shades/hues for validation with both light and dark themes in mind

  • Disabled text inputs are set back in opacity for clearer visual hierarchy

These uplifts are based on user research findings that showed the need for more consistent visual hierarchy and improved interactive states across form elements.


User research on this component

★★★★☆ Confidence rating = High (Informed by multiple rounds of testing)

User research conducted on the Textarea component has shown several key findings:

  • Users appreciate the resizable nature of textareas, particularly when entering longer content

  • The visual distinction between focus, hover, and invalid states helps users understand the current state of the component

  • Some users with motor impairments reported challenges with the resize handles

  • The more prominent visual treatment of invalid states helped users identify and correct errors more quickly

Research included usability testing with diverse participants across multiple devices and platforms, ensuring the component meets the needs of a wide range of users.

Known issues

  • Resize handle usability: The resize handle can be difficult to use for people with motor impairments or when using certain touchscreen devices

  • Character count visibility: When character counters are implemented, they can sometimes be overlooked by users

  • Mobile experience: On mobile devices, textareas can sometimes be difficult to interact with due to virtual keyboard issues

  • Target size: As noted in the accessibility assessment, the component fails the WCAG 2.2 criterion for minimum target size (2.5.8)

More research needed

More user research is needed in the following areas:

  • Optimizing the resize functionality for touchscreen devices

  • Understanding user expectations for auto-expanding textareas versus fixed height with scrollbars

  • Testing different approaches to character count indicators and validation feedback

  • Exploring solutions to address the 2.5.8 Target Size failure for better accessibility compliance

If you have conducted user research that addresses any of these gaps, you can submit your research findings to help improve this component.

Help improve this component

To help make this component useful and up-to-date, you can:

  • Contribute to our Textarea component discussion

  • Submit your user research findings to help improve the Textarea component

  • Propose a change to address known accessibility issues, particularly the target size requirement

  • Help develop better responsive behaviors for mobile experiences


Resources

  • Storybook

  • GitHub

References

  • W3C Web Content Accessibility Guidelines (WCAG) 2.2

  • Australian Government Style Manual

  • Australian Government Design System documentation

  • Digital Service Standard (DSS) requirements

  • Nielsen Norman Group: Form Design Guidelines

Changelog

Version
Date
Changes

1.8.0

23 Jul 2024

Renamed from Text Inputs: Text Area to Textarea, added outline to focus state, removed active state variant

1.7.0

20 Mar 2024

Updated to improve WCAG 2.2 compliance

1.6.0

[Previous date]

Initial component release

Contact us

PreviousSelectNextText field

Last updated 1 month ago

Was this helpful?

If you have a question about the CivicTheme design system or need our help, visit the page for guidance.

Figma
Getting Help