Use a text component when a person needs to enter a short or long written answer. The same component can support names, email addresses, telephone numbers, numeric values, reference codes, free-text explanations and search terms.

Start with the simplest input that captures the information reliably. A specific component or choice pattern is usually better than free text when the answer must come from a known set of options.

Choose the input pattern

flowchart TD
  A[What answer is needed?] --> B{Is it a known set of choices?}
  B -- Yes --> C[Use a choice component]
  B -- No --> D{Does the person need more than a short answer?}
  D -- Yes --> E[Use multi-line text]
  D -- No --> F{Is it a number?}
  F -- Yes --> G[Use number format and numeric limits]
  F -- No --> H[Use single-line text with the closest format]

Write the question and guidance

The label should say exactly what to enter. Put examples, units and constraints in hint text rather than in the label where that keeps the question easier to scan.

Use a short label for review pages only when the full question is too long for a compact summary. Keep a visible label unless the surrounding pattern already provides an unambiguous accessible name.

Set format and validation deliberately

Choose the closest available content format before adding extra rules. This gives the person an input suited to their answer and applies the most relevant built-in validation.

Add limits only when they serve a real business or service need:

• Character limits are useful for identifiers and stored-data limits.
• Word limits are better for explanatory answers. A suggested limit guides without blocking progress; a maximum limit prevents submission above the limit.
• Numeric limits set the acceptable range. Decimal and whole-digit limits control precision and scale.
• Prefix and suffix text can clarify units, such as a currency symbol or kg. They are visual guidance and are not part of the stored answer.

Write a custom error message whenever the default cannot clearly explain the correction. For example: “Enter an amount between 1 and 500” is more helpful than “Invalid value”.

Regular expressions

Use a regular expression only where a standard format cannot validate a stable, well-defined pattern. Keep the expression small, document why it exists, and provide a human-readable error message. Test valid values, near misses, pasted values and empty values.

Do not use a regular expression to enforce a format that people would struggle to recognise or correct. If the underlying identifier is complex, consider a lookup or a different integration pattern instead.

Use multi-line input well

Turn on multi-line input for answers that need sentences or paragraphs. Set the number of visible rows to match the expected length, but do not mistake the visual height for a limit—use a word or character rule if you need one.

Plain text is the appropriate default for person-entered content. Enabling HTML input is a specialised decision: it increases review, security and presentation considerations even when unsafe markup is sanitised. Use it only where your service has a clear approved need and you have tested the rendered output.

Pre-fill and reset values carefully

Text components can be pre-populated with Liquid. This is useful for information already known to the service or for a value based on a previous answer.

Decide whether the person may change the pre-filled value. If they can, provide clear change and reset wording where the Builder supports it. If an upstream answer invalidates a dependent text value, configure a cross-field reset and explain the consequence through the journey design.

Test a new journey, a return to the page, an edited pre-filled value, an upstream change, and a resumed draft. A pre-filled value must never look like a confirmed answer if the person has not had a chance to review it.

Use search-box behaviour for search only

A text component can be configured as a search box. It can reload the page or continue to the next step after a search, and can reveal components such as a results table only after a search has been made.

Use this pattern only when entering a search term is the purpose of the page. Make the search button label explicit, explain what can be searched, and provide a find-all option only where showing every record is safe and useful.

Automatic text changes

Text transformations can standardise input on submission, such as changing case, removing spaces or rounding a numeric value. Apply them only when the transformed value remains what the person reasonably intended to provide.

Be especially cautious with names, addresses, reference codes and free text. Automatic changes can destroy meaningful information. If the stored format differs from what the person entered, make the effect clear in the service design and confirm it on review where needed.

Test checklist

• The label, hint and example make the expected answer clear.
• The selected format matches the information being collected.
• Empty, malformed, boundary and valid values produce the expected outcome.
• Character, word and numeric limits match the stated service rule.
• Prefixes and suffixes clarify a unit without becoming part of the answer.
• Multi-line answers remain readable in review and any confirmation output.
• Pre-population, overrides and resets behave correctly on return and draft resume.
• Search results remain hidden until a valid search when that is the intended pattern.
• Any text transformation preserves the person’s intended meaning.

Related guidance

• Shared component settings
• Choice components
• Write Liquid templates
• Design accessible services