Skip to content
bitboss-ui3.0.0-beta.64

BbTextInput

The single-line text field, and the chrome every other input in the family shares.

import { BbTextInput } from 'bitboss-ui';

On this page

Use it for

Reach for BbTextInput for any short, single-line string: a name, an email, a URL, a coupon code, a search box.

Use something else when

Also see: Validated forms.

This page also defines the shared field chrome used by the other inputs.

Passthrough

Hover or tap a part to outline it. The toggles turn on loading, errors and warnings where the component has them; only parts get a row.

https://.bitboss.appGuidance while the control is focused.

Default

Pass a label and bind v-model.

Model: "Vantera"

The model is string | null. An emptied field emits null, so write value ?? '' for an API that insists on a string. To emit '' instead, set null-value="string" on one field, or the plugin option formControls.textInputNullValue once for the whole app.

label does not set name. Pass name for native form submission and an explicit id for stable prerendered markup.

Coming from v2template ref removed

v3 removed the imperative handle: focus(), blur() and select() are gone. A leftover inputRef.value?.focus() is undefined at runtime, not a compile error. Use autofocus for focus on mount. For anything else, take the native <input> through passthrough, :pt="{ input: { attrs: { ref: (el) => (input = el) } } }", and call input.focus() on it.

Label modes

label-mode puts the label above the field (outside, the default), resting inside it like a placeholder (floating), or pinned small inside the top edge (inside).

Set the product default with defaultInputLabelMode. Do not combine floating with a placeholder; both occupy the same space.

floating alone is not a prop; it falls through to the root and does nothing:

diff
- <BbTextInput v-model="email" label="Email" floating />
+ <BbTextInput v-model="email" label="Email" label-mode="floating" />

hide-label drops the label from view and keeps the accessible name, which is what a search box with nothing but a placeholder wants. Dropping label itself is never the answer.

Type and keyboard

type tells the browser what kind of text this is: text, email, url, tel, search, password. That is the whole list.

v3 narrowed it to those six. type="number" and type="date" no longer compile, and the fix is a different component rather than a different value:

diff
- <BbTextInput v-model="qty" type="number" label="Quantity" />
+ <BbNumberInput v-model="qty" label="Quantity" />

- <BbTextInput v-model="due" type="date" label="Due date" />
+ <BbDatePickerInput v-model="due" label="Due date" />

Set autocomplete in auth and checkout flows. Use input-mode to request the right mobile keyboard without changing the value type.

There is no revealable prop. A reveal toggle is a type that changes plus a button in the #append slot.

Native attributes that only mean something on the input, such as maxlength, pattern, spellcheck and enterkeyhint, go straight to the <input>. Any other attribute lands on the outer element; reach the input with pt:input instead.

Masks

Pass a maska config to mask and the field formats as the user types: card numbers, VAT ids, licence keys.

Card model
4242424242424242
VAT model
null

By default the model holds the unmasked value: the field shows 4242 4242 4242 4242, v-model holds 4242424242424242. Pass emit-masked when the formatted string is the value, as it is for a VAT id people copy and paste. Either way an emptied field emits null, like an unmasked one.

Masks format, they do not validate. A complete but wrong card number passes the mask and still needs an error.

Description and hint

Two channels sit around the field, and the difference is timing. description is always visible between the label and the field, read before typing. hint appears below the field on focus, read while typing.

Characters: 0 of 20
Include the scheme, as in https://vantera.io

persistent-hint keeps the hint visible. Both channels are connected through aria-describedby, so keep them useful and concise.

counter adds a character count at the end of the hint row. With a native maxlength it reads 12 / 20 and the input stops at the limit.

Errors and warnings

errors says the value cannot be accepted. warnings says the value is accepted and worth a second look. Two channels, not one channel with a severity flag.

Enter a complete email address, including the domain.
Matches an existing customer. Check before creating a duplicate.

Non-empty messages imply their visual state. Errors set aria-invalid; warnings do not. When both exist, errors win.

Bind server-side errors straight in. With Inertia:

vue
<BbTextInput
    v-model="form.email"
    label="Billing email"
    type="email"
    autocomplete="email"
    :errors="form.errors.email"
/>

For client rules, put the field inside a BbForm and give it rules. It joins the form under its name, so it needs no v-model. Tab out of the empty Email, or send the invite, to see the rule.

Invite a teammate

They join the Design workspace as an editor.

A field joined to a BbForm is checked as required through rules="required" or the form's schema, and the asterisk beside the label follows. The required prop there is a hint: it draws the asterisk and tells assistive technology, and an empty field still submits, so use it when the server does the checking.

The rule messages render in the same errors channel, merged with any errors you pass. A field checks itself when you leave it, then on every keystroke while it shows an error; validation-mode changes that timing. Outside a BbForm, rules do nothing, and required is the right prop: it forwards to the native input and produces no message of its own.

A field inside a form that is not form data, such as a filter, takes formless: it stays out of the data, the validation and the save lock. When the label reads badly in a message ("Search orders is required"), set validation-label on a joined field.

Clearable, loading, disabled and readonly

Four flags change what the field lets you do, and only two of them stop anything.

Checking this code…
Chosen when the workspace was created.

clearable emits null and restores focus. loading only shows status; it does not lock the field. disabled removes interaction, while readonly keeps the value focusable and copyable.

Icons and affixes

The slots ring the field from the value outward. prefix and suffix are short text at the inner edges of the box, either side of the value. prepend and append sit inside the chrome. prepend:outer and append:outer sit beside the field entirely.

vantera.io/
@vantera.io

Icons (prepend:icon, append:icon) and prefix/suffix text are decoration and never take focus. A small button can go in #append, as the password toggle does; anything larger sits in append:outer.

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

Variants, density and layout

variant changes only the colours of the box: outline (default), secondary or ghost. compact reduces the control height. Use one density across a form.

A search box in a table toolbar belongs to the bar, not to a form. variant="none" is the blank base for it: the box keeps its height and padding, loses every colour, and pt:box takes your classes. The focus ring goes with the colours, so draw your own focus state.

Orders

layout puts the label beside the field instead of above it. layout="horizontal" splits the row 50/50. Two space-separated tokens read as a ratio: "xx xxxxx" gives the label two parts and the field five. Use the same value on every row so the fields line up. reverse swaps the two columns. auto keeps both at their natural width, label-fill gives the free space to the label (a settings row with a short field on the right), and input-fill gives it to the field. None of them wraps, so stack them on a phone with a per-breakpoint map: :layout="{ default: 'vertical', md: 'xx xxxxx' }", as the demo does.

Billing details

layout applies only while the resolved label mode is outside, which is the library default. floating and inside put the label inside the field and always stack vertically. The resolved mode is label-mode, or defaultInputLabelMode when the prop is unset.

Coming from v2input wrapper classes

Selectors on .bb-common-input-inner-container* move to .bb-field-input*. The layout class bb-base-input-container__layout--hidden-label is gone as well: it always appeared on exactly the same condition as --reverse, and nothing in the library ever painted it. Target .bb-field__layout--reverse.