Lily Design System™

Hint

A hint provides subtle, contextual guidance text associated with a form control. It is typically displayed near an input field to clarify expected formats, explain functionality, or offer examples. The component renders a <p> element with an optional id for linking to a form control via aria-describedby.

This component is designed to work alongside form inputs where the consumer links the hint to the input using aria-describedby on the input element pointing to the hint's id. This ensures screen readers announce the hint text when the user focuses the associated input.

Example

Enter your full name as shown on your ID
Show demo markup 
<span class="hint">Enter your full name as shown on your ID</span>
Usage example 
<script lang="ts">
    import Hint from "./Hint.svelte";
</script>

<Hint id="email-hint">Enter your work email</Hint>
<input type="email" aria-describedby="email-hint" />
Show Svelte source 
// In your Svelte component:
import Hint from "lily-design-system-svelte-headless/components/Hint/Hint.svelte";

<Hint>
  <!-- content -->
</Hint>

Usage

<Field label="What is your NHS number?">
  <Hint id="nhs-number-hint">This is a 10-digit number, like 485 777 3456. You can find it on any letter the NHS has sent you.</Hint>
  <TextInput label="NHS number" inputmode="numeric" aria-describedby="nhs-number-hint" />
</Field>
<Field label="Email address">
  <Hint id="email-hint">We will only use this to send you a confirmation</Hint>
  <EmailInput label="Email address" aria-describedby="email-hint" />
</Field>
<Field label="Date of birth">
  <Hint id="dob-hint">For example, 15 3 1984</Hint>
  <DateInput label="Date of birth" aria-describedby="dob-hint" />
</Field>

Props

  • id: string (default: undefined) -- ID for linking via aria-describedby on the associated form control
  • children: slot (required) -- hint text content

Keyboard Interactions

None -- this component is a passive text element. It is announced by screen readers when the associated form control receives focus.

ARIA

  • id={id} -- provides a target for aria-describedby on the associated form control

When to Use

  • Use to help the majority of users understand how to answer a form question
  • Use to show the expected format of an answer, such as "For example, 15 3 1984" or "Like name@example.com"
  • Use to explain where users can find the information being asked for
  • Use as a single short phrase or sentence -- keep it concise because screen readers read the entire hint aloud

When Not to Use

  • Do not use for long, detailed explanations -- screen readers read the entire hint aloud, which frustrates users; use InformationCallout instead
  • Do not include links inside hint text -- screen readers do not announce that hint text contains a link
  • Do not include interactive elements like Details inside hint text -- users in screen reader form mode cannot interact with them
  • Do not use as a substitute for a clear Label -- the label should make the question understandable on its own
  • Do not use for error messages -- use ErrorMessage instead

Headless

This headless component provides a <p> element with an optional id for linking to a form control via aria-describedby. The consumer provides all visual styling including font size, color, spacing, and position relative to the input.

Styles

The consumer provides all CSS styling. The component renders with a .hint class for targeting. No default styles are included — this is a fully headless component.

Testing

  • Verify the component renders a <span> element with class hint
  • Verify pass-through attributes are applied

Advice

  • Designers: Place hint text directly below the label and above the input. Use a lighter color or smaller font to distinguish it from labels and error messages.
  • Developers: Always set the id prop and add aria-describedby to the associated input so screen readers announce the hint when the input is focused.

Implementation Notes

  • Renders a <p> element containing the children slot
  • Accepts an optional id prop for aria-describedby linking with form controls
  • Spreads restProps onto the <p> for consumer customization
  • The consumer is responsible for adding aria-describedby to the associated input

Related components

  • error-message — an error message associated with a form field
  • field — a form field wrapper with label, input, and error message
  • label — a label associated with a form input

References

  • WAI Forms Tutorial - Instructions: https://www.w3.org/WAI/tutorials/forms/instructions/

Canonical contract

Generated from this component's canonical metadata — the machine-checked source the implementations are held to.

Metadata

  • Component: hint
  • PascalCase: Hint
  • Description: hint text providing guidance for a form field
  • Status: stable — exercised in composed page flows under e2e and axe, beyond the per-component checks
  • HTML tag: <span>
  • CSS class: .hint
  • Interactive: no

ARIA

  • id={id} -- provides a target for aria-describedby on the associated form control

Keyboard

  • No keyboard interactions — this is a passive element

Props

  • id: string (default: undefined) -- ID for linking via aria-describedby on the associated form control
  • children: slot (required) -- hint text content