BbTextInput

Name of the icon to be added at the end of the input.

The append icon position shows one thing at a time, by priority: clear button, then spinner, then the error or warning icon, then this. On a clearable or validated field it disappears as soon as there is a value to clear or an error to show. Put anything that must stay visible in append:outer.

Guides to the browser as to the type of information expected in the field.

Set it on every field in an auth or checkout flow. Search and filter boxes need autocomplete="off" just as much: they are text inputs on a page that has seen a login, so the browser offers a saved email over the results being filtered.

Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field.

The replacement for the template-ref API v3 removed: there is no exposed focus() / blur() / select(), and a leftover call is undefined at runtime rather than a compile error. Use at most one per view. For anything more, take the native <input> through pt:input (attrs: { ref }).

Displays a clear button when the input has a value and is being interacted with.

There is no clear event: the button emits null through the model, so watch the model instead. Suppressed on disabled and readonly fields, and never worth rebuilding in an append slot.

Compact density: the field uses the -compact twins of --bb-input-h, --bb-input-py and --bb-label-spacing-y, so a --bb-input-h set on the component is ignored while it is on. Size a compact field with --bb-input-h-compact (and --bb-input-py-compact).

A property of a view, not of a field. Two densities in one form read as a seam.

Shows a character count at the end of the hint row: 42, or 42 / 140 with the native maxlength (which also stops input). It brightens from 90 % and takes the warning colour at the limit; screen readers hear it only when it crosses 90 % or the limit.

Text between the label and the input. Unlike the hint it is always visible; it joins the input's aria-describedby after any errors / warnings, before the hint.

Always visible, and read before typing: the place for an instruction. hint is the one that speaks while the field has focus.

Disables the component.

Blocks the keyboard too, so a disabled value is unreachable for someone navigating that way. Prefer readonly for derived or provisioned values.

Emits the masked value of the input.

Off by default, so the model holds the digits while the field shows the separators. Turn it on when the formatted string is the value you store, and do not strip formatting server-side that was never sent.

Error messages under the field, a string or array, in an aria-live="polite" region and first in the control's aria-describedby, so they are re-read when it regains focus.

A non-empty value implies the error state, so has-errors is only for when the message lives elsewhere. Rendered in an aria-live region and referenced first from aria-describedby, so it is announced on change and re-read on focus.

Keep this control out of the enclosing BbForm entirely: not submitted, not dirty, not reset, not validated. For a control that is not form data (a filter, a "show advanced" switch).

For a field inside a BbForm that is not form data, such as a filter above a list. Without it, a field with no name joins the form under its label slug.

Define if the component should be in an error state. It usually attaches a CSS class for styling purposes.

Sets aria-invalid and the error chrome without a message, for a field whose error is reported by a form-level summary.

Define if the component should be in a warning state. Same chrome as errors with --bb-warn; errors take priority.

The warning counterpart of has-errors: amber chrome, no aria-invalid. Errors win when both states are set.

Visually hides the label of the input while maintaining accessibility.

Keeps the accessible name and removes only the visible text. It is the answer for a search box that shows just a placeholder; omitting label is not the same thing and never is.

Text box to be displayed near the input, usually to indicate instructions.

Shown while the field has focus, unless persistent-hint keeps it. A form where every field carries permanent text below it is a form nobody reads.

The id of the native control; the label's for and the description and message ids derive from it. Generated when omitted.

Vertical position of the control in a side-by-side row; not inputPosition, the horizontal one. Omitted, the control's first line meets the label's.

The inputmode of the input.

Steers the mobile keyboard independently of type: that is how a masked code field stays type="text" and still gets a number pad.

Text content of the label of the element.

Required, and display and accessibility only: it does not set the name attribute. Hide it with hide-label rather than dropping it.

Vertical position of the label block in a side-by-side row; not labelPosition, the horizontal one. Omitted, the label's first line meets the control's.

Label rendering mode.

A bare floating attribute is not a prop and never was: it falls through $attrs and does nothing. The spelling is label-mode="floating". Unset, the value comes from defaultInputLabelMode in the plugin config, so a project can float every field without touching call sites.

Sets the text alignment of the label.

How label and input sit together: 'vertical', 'horizontal' (50/50), 'auto', 'label-fill', 'input-fill', a ratio like 'xx xxxxx', or a per-breakpoint map ({ default: 'vertical', md: 'xx xxxxx' }).

Applies only while the resolved label mode is outside. floating and inside embed the label in the field and force the vertical layout, ignoring this without a warning. Check defaultInputLabelMode before concluding the prop is broken.

Sets the component in a loading state, usually triggering some visual styles.

Visual only: the field stays editable. If the value must not change while an async check runs, write that guard yourself and tag requests so a stale response cannot overwrite a newer one.

A maska options object, not a string: { mask: '#### #### #### ####' }. Please visit https://beholdr.github.io/maska/v3 for syntax examples.

A maska config, live-reactive: changing the options reformats the current value. Masks format, they do not validate: a complete-but-wrong value still needs an error.

Used by v-model.

Defines the name of the input.

Unset, the rendered <input> carries no name at all, so a native form post or a FormData read drops the value silently. label does not fill this in.

What the field emits once emptied (typing, the clear button, an empty mask): 'null' emits null, 'string' emits ''. Unset: formControls.textInputNullValue ('null'). With 'string', the update:modelValue payload types as string.

Keeps the hint displayed.

Text shown while the field is empty.

Name of the icon to be added at the start of the input.

Passthrough, object form: { box: '…', 'box:errors': '…' } — the same keys as the pt:* attributes without the prefix. See the pt:<part> row.

Passthrough, attribute form: one attribute per part, pt:<part>, and per part and state, pt:<part>:<state>. Parts: box, clear, counter, description, hint, icon, input, label, message, prefix, root, spinner, suffix. States: atLimit, disabled, errors, ghost, hasValue, loading, nearLimit, outline, readonly, secondary, warnings.

Sets the input in a readonly state.

Keeps the value focusable, selectable and copyable while refusing edits: the right choice for a value the user did not set but may need to read or copy.

Sets the native required attribute, for a plain <form>. Inside a BbForm it is an error (nothing enforces it): use rules="required" or the form schema instead.

Forwards to the native input for the browser's own validation. It does not produce a message: errors still owns that.

Reverses the layout. Applicable in every direction the order of the label and the input is swapped.

vee-validate rules for this field. Only inside a BbForm.

Read only inside a BbForm; outside one the field is plain and the rules do nothing. Whatever you pass to errors is merged with the rule messages rather than replaced.

Type of the input. Restricted to the textual input types this component supports — use BbNumberInput for numbers and BbDatePickerInput for dates.

Narrowed in v3 to the text-like types. type="number" and type="date" no longer compile; those values move to BbNumberInput and BbDatePickerInput. There is no revealable: a password toggle is a type that changes plus a button in #append.

The field's name in validation messages ({field}): "Email is not valid". Defaults to the label (or legend), then "This field"; never the name. Set it when the label is hidden or reads badly in a sentence (icon-only, a question). BbForm only.

When the field validates: aggressive (each change), balanced (on leave, then live while in error), lazy (on leave), submit-only, submit-live. Unset: the BbForm's validation-mode, then formControls.validationMode ('balanced'). BbForm only.

The field box's look, with BbButton's names and tokens. Colours only, so a form never reflows; 'ghost' has no border in any state, 'none' no look at all (you own hover, focus and the states). Register more with the plugin's inputVariants.

Warning messages under the field, a string or array: amber, in their own aria-live region and in the control's aria-describedby after the errors. Non-empty turns on the warning state; errors win when both are set.

The amber channel, for a value that is accepted and still worth a second look. Unlike errors it does not set aria-invalid, and it is suppressed entirely when the field also has errors.

string | null: an emptied field emits null, or '' when the plugin option formControls.textInputNullValue says so. Inside a BbForm the binding is optional: the form holds the value under name.

Emitted when the native input loses focus. Forwards the original DOM FocusEvent.

Emitted when the native input fires a change event. Forwards the original DOM Event.

Fires on commit (blur or Enter), which makes it the right hook for an expensive side effect. input fires on every keystroke.

Emitted when the input receives a click interaction. Forwards the original DOM MouseEvent.

Emitted when a composition session ends (e.g. CJK IME confirmed). Forwards the original DOM CompositionEvent.

Emitted when a composition session starts (e.g. CJK IME begins). Forwards the original DOM CompositionEvent.

Emitted when the native input gains focus. Forwards the original DOM FocusEvent.

Emitted on native input events from the text field. Forwards the original DOM Event.

Emitted for keyboard interaction on the input. Forwards the original DOM KeyboardEvent.

Emitted when a key is released over the input. Forwards the original DOM KeyboardEvent.

Emitted when a pointing device button is pressed over the input. Forwards the original DOM MouseEvent.

Emitted when a pointing device button is released over the input. Forwards the original DOM MouseEvent.

Emitted when content is pasted into the input. Forwards the original DOM ClipboardEvent.

Emitted when the value changes. Carries the new string, or the empty value (null-value, else the app's, null by default) when emptied. When mask is set, emits the masked or unmasked string depending on emitMasked.

Content rendered after the text input, at the end of the field box.

Content rendered after the entire text input control, outside the input chrome.

Outside the field chrome, and the only affix position that may hold something interactive.

Replaces the description text. Provided alone (no description prop) it still renders the description region and wires it into aria-describedby.

Replaces the default label text rendered above the input.

Receives { text, hasErrors, hasWarnings }, plus showAsterisk while the required marker shows, so a custom label can react to the field state. Replacing the label also replaces the marker: put it back with <BbAsterisk v-if="showAsterisk" />, or unconditionally on a required field in an app that turned requiredAsterisk off.

Inline content rendered at the start of the input field area, before the typed text.

Short inline text at the inner edge of the box, beside the value. Affixes never take focus, so a click here lands in the input: a small button belongs in #append, a larger one in append:outer.

Content rendered before the text input, at the start of the field box.

Content rendered before the entire text input control, outside the input chrome.

Inline content rendered at the end of the input field area, after the typed text.