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, ortel
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
| Part | Element | Description |
|---|---|---|
| 1 | Label | Persistent field name shown through the label slot |
| 2 | Control | The bordered container that groups the editable field and optional affordances |
| 3 | Native input | The actual text input used for typing, autofill, and form submission |
| 4 | Prefix | Optional leading content inside the control, usually an icon |
| 5 | Suffix | Optional trailing content inside the control, often a status or supporting icon |
| 6 | Helper text | Supporting guidance or validation feedback shown below the field |
| 7 | Clear button | Optional action that appears when the field has a value and clearing is enabled |
Design guidelines
Use this sequence when you define an input:Choose the right type
Start with the most specific native
type that matches the data, such as email, password, search, tel, or number.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.
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 thevalue 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 thedisabled attribute when the input field should be visible but non-editable.
Options
Validation
Use this variant for validation feedback by settingvalidation-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.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, andstepto the native input element. - Built in: when
disabledis set, the native input receivesaria-disabled="true"so assistive technologies can detect the unavailable state. - Built in: the clear button uses
clearButtonLabelas its accessible name, and the default clear icon is markedaria-hidden="true". - Built in: the component participates in forms and can surface native required-state validity when you combine
requiredwithformValidationMessage. - You must: provide meaningful content in the
labelslot 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
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
autocapitalize | autocapitalize | Controls capitalization behavior for typed text | string | "off" |
autocomplete | autocomplete | Hints whether and how the browser should autocomplete the field | string | "off" |
autofocus | autofocus | If true, the input is focused on component render | boolean | false |
clearButtonLabel | clear-button-label | Accessible label for the clear button | string | "Clear value" |
debounceTime | debounce-time | Delay before the bqInput event is emitted after the value changes | number | 0 |
disableClear | disable-clear | If true, the clear button is hidden | boolean | false |
disabled | disabled | Disables the input | boolean | false |
form | form | ID of the form the input belongs to | string | undefined |
formValidationMessage | form-validation-message | Native validation message used when required is set | string | undefined |
inputmode | inputmode | Hints the most helpful virtual keyboard for the expected value | string | undefined |
max | max | Maximum accepted value for date and number types | number | string | undefined |
maxlength | maxlength | Maximum accepted number of characters | number | undefined |
min | min | Minimum accepted value for date and number types | number | string | undefined |
minlength | minlength | Minimum accepted number of characters | number | undefined |
name | name | Name of the underlying input | string | undefined |
pattern | pattern | Regular expression the value should match | string | undefined |
placeholder | placeholder | Placeholder text shown when the field is empty | string | undefined |
readonly | readonly | If true, the value can be focused and copied but not edited | boolean | undefined |
required | required | Marks the field as required | boolean | undefined |
step | step | Granularity constraint for compatible input types | "any" | number | undefined |
type | type | Native input type to render | "date" | "datetime-local" | "email" | "number" | "password" | "search" | "tel" | "text" | "time" | "url" | "text" |
validationStatus | validation-status | Validation state of the control | "error" | "none" | "success" | "warning" | "none" |
value | value | Current input value | number | string | string[] | undefined |
Events
| Event | Description | Type |
|---|---|---|
bqBlur | Fired when the input loses focus | CustomEvent<HTMLBqInputElement> |
bqChange | Fired when the value changes and the input loses focus | CustomEvent<{ value: string | number | string[]; el: HTMLBqInputElement }> |
bqClear | Fired when the value is cleared | CustomEvent<HTMLBqInputElement> |
bqFocus | Fired when the input receives focus | CustomEvent<HTMLBqInputElement> |
bqInput | Fired on every keystroke as the value changes | CustomEvent<{ value: string | number | string[]; el: HTMLBqInputElement }> |
Slots
| Slot | Description |
|---|---|
label | Label content for the field |
prefix | Optional leading content inside the control |
suffix | Optional trailing content inside the control |
helper-text | Supporting text displayed below the field |
clear-icon | Replaces the default clear icon |
Shadow parts
| Part | Description |
|---|---|
base | Base wrapper for the component |
button | Native button used for the clear action |
clear-btn | Clear button container |
control | Input control wrapper |
helper-text | Helper text container |
input | Native HTML input element |
label | Label slot container |
prefix | Prefix slot container |
suffix | Suffix slot container |
CSS custom properties
Resources
Interactive playground
Explore input variants and states in Storybook.
Source code
View the component source on GitHub.