Skip to content

Proposal: add configurable strictness for placeholder-only labels #343

Description

@TyrGo

Summary
Introduce an optional strictness configuration that lets users treat placeholder-only inputs and textareas as accessibility violations, even though axe-core seems to me to permit them by default.

Motivation
Some consumers rely on stricter labeling rules. As per MDN:

**The aria-placeholder is used in addition to, not instead of, a label. They have different purposes and different functionality. A label explains what kind of information is expected. Placeholder text provides a hint about the expected value.

Warning: Using a placeholder instead of a visible label harms accessibility and usability for many users including older users and users with cognitive, mobility, fine motor skill and vision impairments. Labels are better: they are always visible and they provide for a larger hit region to focus on the control. Placeholders have several drawbacks: they disappear when the control has any value including just white space, they can confuse users into thinking the value is pre-filled, and the default color has insufficient contrast.**

Proposed changes

  • Add a strictness?: StrictnessOptions property to AccentedOptions, starting with a placeholderLabelsAreInsufficient flag.
  • In accented.ts, use reference-counted axe.configure calls so enabling the flag disables non-empty-placeholder, and returning to normal re-enables it when no strict instances remain.
  • Extend validate-options.ts to guard the strictness object and the new boolean field.
  • Export StrictnessOptions so TypeScript consumers see the shape and defaults.
  • Update documentation (api.mdx), changelog, and playground/dev app examples to mention the option.
  • Add Playwright coverage in main.spec.ts verifying both default and strict behavior.
  • Include a README snippet showing how to enable the stricter mode.

Extensibility
Modeling strictness as an object means future toggles can be added without breaking existing callers.

I’m happy to implement this if you agree with the general direction.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions