Skip to main content
BEEQ Input component overview

Input component overview

Inputs let users enter a short value in a familiar, single-line control. Use them when people need to type information directly and you want the field to support labels, helper text, inline validation, and optional prefix or suffix content.
Use bq-input for single-line entry. If the answer may span multiple lines, use a textarea. If the user must pick from known options, use a select or dropdown. If the value is a date, use a date picker.

​
When to use

Use inputs when
  • You need a single-line field for names, email addresses, passwords, codes, URLs, or similar short values
  • Typing is faster than choosing from a list
  • Users benefit from inline helper text, validation, or browser autofill
  • The field should accept semantic input types such as email, password, search, or tel

Do not use inputs when
  • The user must choose from a fixed set of options
  • The answer is likely to be long or multi-line
  • A specialized control would reduce errors, such as a date picker or autocomplete pattern
  • The field purpose would only be understandable through placeholder text

​
Patterns

Single-line form field

The default pattern for account details, profile data, contact information, and short reference values.

Credential field

Works well for passwords, one-time codes, and other controlled text values where labels and validation matter.

Search or filter entry

Use an input when users refine content by typing a term, especially when the field benefits from a search-specific type or icon.

Structured browser-assisted input

Inputs support browser features such as autofill, autocomplete, and keyboard hints, which help users finish forms faster and with fewer mistakes.

​
Anatomy

BEEQ Input component anatomy

Input component anatomy

An input combines a persistent label with a single-line text field and optional supporting content. Keep the label visible, use helper text for guidance or feedback, and treat placeholder text as an example rather than an instruction.

​
Design guidelines

Use this sequence when you define an input:
1

Choose the right type

Start with the most specific native type that matches the data, such as email, password, search, tel, or number.
2

Write the label first

Make the field purpose clear with a persistent label. Use helper text for extra context and keep placeholder text for examples only.
3

Support fast completion

Add semantic attributes such as autocomplete, required, and pattern only when they meaningfully improve completion or validation.
When the field has a value and disable-clear is not set, the component can surface a built-in clear action. You do not need to build a separate clear button for common text-entry cases.

​
Usage

​
Default

Use the default type of input when you want to provide a simple, versatile field for gathering user input. You do not need to specify any additional property that already uses its default value.

​
Value

Use the value attribute to provide a convenient solution for scenarios where the initial input is predefined.

​
Prefix

Use the prefix slot when you want to place an icon before the input value to provide extra context.

​
Suffix

Use the suffix slot when you want to add an icon after the input field for extra context or feedback.

​
Prefix and Suffix

This variant combines both prefix and suffix features within the same input.

​
Disabled

Use the disabled attribute when the input field should be visible but non-editable.

​
Options

​
Validation

Use this variant for validation feedback by setting validation-status to error, success, warning, or none.

​
Label with “Optional”

Use this style when you want to include an optional marker to provide additional context.

​
Label with “Info Tooltip”

Use this style when you want to include an informational tooltip alongside the input label.

​
With no label

Use this variant when the surrounding context already makes the field purpose clear and a visible label would be redundant.

​
With no Helper Text

Use this variant when the field does not require supplementary guidance.

​
Form integration

bq-input submits its current string value with the form. Combine name, required, and form-validation-message when the field must pass native validation before submission.

​
Best practices

DoKeep labels short, specific, and visible after users start typing.

Don’tRely on placeholder text as the only explanation of what the field is for.

DoWrite helper text that explains format, constraints, or what happens next in plain language.

Don’tFill the space under the field with long, repetitive instructions users will skip.

DoMatch field type, width, and ordering to the data people are expected to enter.

Don’tMake users jump across multiple columns or guess which fields belong together.

DoExplain validation close to the field and tell users how to recover from an error.

Don’tUse color alone to communicate validity or leave users guessing which format is required.

​
Accessibility

  • Built in: the component forwards semantic input attributes such as type, autocomplete, required, readonly, min, max, maxlength, minlength, pattern, and step to the native input element.
  • Built in: when disabled is set, the native input receives aria-disabled="true" so assistive technologies can detect the unavailable state.
  • Built in: the clear button uses clearButtonLabel as its accessible name, and the default clear icon is marked aria-hidden="true".
  • Built in: the component participates in forms and can surface native required-state validity when you combine required with formValidationMessage.
  • You must: provide meaningful content in the label slot for most cases, even when the surrounding layout makes the field purpose look obvious visually.
  • You must: treat helper and validation text as instructions, not decoration. Keep it concise and make recovery steps explicit.
  • You must: avoid placeholder-only labeling because placeholder text disappears as soon as the user types.
  • You must: add alternate context when you intentionally omit the visible label, so screen reader and keyboard users still understand the field purpose.

​
API reference

​
Properties

​
Events

​
Slots

​
Shadow parts

​
CSS custom properties

Learn more about styling with shadow parts and CSS custom properties.

​
Resources

Interactive playground

Explore input variants and states in Storybook.

Source code

View the component source on GitHub.