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
  • 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

Text field

PreviousTextareaNextHeading

Last updated 1 month ago

Was this helpful?

The Textfield component is a form input element that allows users to enter and edit single-line text, providing visual feedback on the input state.

When to use

Use the Textfield component when you need to collect single-line text input from users, such as names, email addresses, search queries, or other short form data. Textfields are essential for forms and interactive interfaces where user input is required.

When not to use

Do not use the Textfield component when:

  • The user needs to enter multiple lines of text - use a Textarea component instead

  • The input is limited to a specific format with validation (such as dates or numeric values) - consider using a specialised input type

  • The user needs to select from pre-defined options - use radio buttons, checkboxes, or select menus instead

  • The input data requires enhanced security (such as passwords) - use a specialised password field with appropriate security measures


Best practice guidelines

  • Clear labelling: Always provide a clear, descriptive label for each textfield that indicates what information is required.

  • Input validation: Implement appropriate validation with clear error messages to help users correct input errors.

  • Visual states: Ensure textfields have distinct visual states (default, hover, focus, disabled, invalid) to provide clear feedback to users.

  • Responsive design: Design textfields to adapt appropriately to different screen sizes and device types.

  • Accessibility: Ensure textfields are accessible to all users, including those using assistive technologies.

  • Consistent styling: Maintain consistent styling of textfields throughout your interface to provide a cohesive user experience.

  • Placeholder text: Use placeholder text to provide hints or examples, but never as a replacement for labels.

  • Field width: Set appropriate field widths that correspond to the expected input length to provide visual cues about the expected content.

  • Required fields: Clearly indicate which fields are required versus optional to set clear expectations for users.

  • Error recovery: Provide clear error messages and guidance for recovery when input validation fails.


Accessibility

According to the CivicTheme v1.7.0 Accessibility Assessments, the Textfield component has been tested against WCAG 2.2 standards. The component passes most accessibility requirements but fails on target size requirements.

Summary of the accessibility test results:

WCAG 2.2 Criterion
Status
Details

1.4.3 Contrast (Minimum)

Pass

Contrast meets minimum requirements

1.4.4 Text Resizing

Pass

Text can be resized without loss of content or functionality

1.4.12 Text Spacing

Pass

Content can be presented without loss when text spacing is adjusted

2.1.1 Keyboard Accessibility

Pass

Functionality is operable through a keyboard interface

2.4.7 Focus Visibility

Pass

Keyboard focus indicator is visible

2.5.3 Label in Name

Pass

Component passes label in name requirements

3.2.2 Input Handling

Pass

Changing the setting of any user interface component does not automatically cause a change of context

2.5.8 Target Size (Minimum)

Fail

The size of the target for pointer inputs does not meet the minimum requirement of 24 by 24 CSS pixels

Security

When implementing Textfield components, consider these security aspects:

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

  • Use appropriate form validation on both client and server sides

  • Consider data privacy implications when collecting personal information

  • Follow secure coding practices to prevent data leakage or unauthorised access

Component inspiration and uplift

This component has been modelled after the Text Input component from the former Australian Government Design System (AGDS). According to the CivicTheme AGDS Compliance Statements document, the Textfield component has been uplifted in the following ways:

  • A thinner 1px border is used in the resting state for a cleaner, more accessible look

  • A darker background colour is applied to balance the thinner border and distinguish from the body background

  • An additional hover state is included which presents a 2px border (matching the original AGDS appearance)

  • Invalid inputs use distinct colour variations for better contrast ratios in both light and dark themes

  • Disabled text inputs are set back in opacity while maintaining sufficient contrast

  • Input widths can be configured according to the original AGDS guidelines

These enhancements improve both usability and accessibility while maintaining compatibility with the original AGDS design principles.


User research on this component

★★★★☆ Confidence rating = High (Informed by research but with some limitations)

Based on the available information and applying the evaluation criteria from the scoring guidance, the Textfield component shows strong usability characteristics but has known accessibility limitations around target size.

The component follows established design patterns that have been validated through testing across multiple government design systems. Textfields represent a fundamental form element with well-established usage patterns, and CivicTheme's implementation incorporates best practices for input validation, visual states, and feedback mechanisms.

The component shows strong visual design with appropriate contrast levels and properly implemented states (default, hover, focus, invalid, disabled) that clearly communicate the component's status to users. However, the identified target size issue affects the component's accessibility score.

Known issues

  • Target size limitations: As noted in the accessibility assessment, the Textfield component fails to meet WCAG 2.2 requirements for minimum target size (24x24 CSS pixels).

  • Mobile usability challenges: On smaller screens, textfields may be more difficult to interact with due to the limited target size, potentially causing input errors.

  • Responsive behaviour: More testing may be needed to ensure consistent behaviour across all viewport sizes and device types.

More research needed

Additional research would be beneficial in the following areas:

  • Testing with users who have motor control difficulties to assess the impact of the target size issue

  • Evaluating performance with various input methods (touch, stylus, keyboard, voice)

  • Testing with diverse user groups to ensure the component works effectively across different contexts and use cases

  • Assessing how the component performs as part of complex form implementations

Help improve this component

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

  • Contribute to discussions about addressing the target size accessibility issue

  • Submit user research findings that could improve the Textfield implementation

  • Propose code changes to enhance the component's accessibility and usability

  • Test the component across different devices and contexts and report findings


Resources

  • Storybook

  • GitHub

References

Changelog

Version
Date
Changes

1.8.0

23 Jul 2024

Renamed Text Inputs: Text Field to Textfield, added outline to focus state and removed active state variant

1.7.0

20 Mar 2024

Updated for WCAG 2.2 compliance assessment

Contact us

Check out our to learn more.

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

contributing section
Figma
Nielsen Norman Group. (2019). Form Design Guidelines
W3C. (2022). Web Content Accessibility Guidelines (WCAG) 2.2
Digital Service Standard (2023)
Australian Government Style Manual
Getting Help