[[toc]]
Create various type inputs such as: text
, password
, number
, url
, email
, search
, range
, date
and more.
<template>
<BFormInput v-model="selectedText" placeholder="Enter your name" />
<div class="mt-2">Value: {{ selectedText }}</div>
</template>
<script setup lang="ts">
const selectedText = ref('')
</script>
BFormInput
defaults to a text
input, but you can set the type
prop to one of the supported native browser HTML5 types: text
, password
, email
, number
, url
, tel
, search
, date
, datetime
, datetime-local
, month
, week
, time
, range
, or color
.
{{ type }}
:
<template>
<BRow class="my-1" v-for="type in inputTypes" :key="type">
<BCol sm="3">
<label :for="`type-${type}`"
>Type <code>{{ type }}</code
>:</label
>
</BCol>
<BCol sm="9">
<BFormInput :id="`type-${type}`" :type="type" />
</BCol>
</BRow>
</template>
<script setup lang="ts">
const inputTypes = [
'text',
'number',
'email',
'password',
'search',
'url',
'tel',
'date',
'time',
'range',
'color',
'datetime',
'datetime-local',
'month',
'week',
]
</script>
If the type
prop is set to an input type that is not supported (see above), a text
input will be rendered and a console warning will be issued.
Caveats with input types:
- Not all browsers support all input types, nor do some types render in the same format across browser types/versions. Refer to Can I use
- Browsers that do not support a particular type will fall back to a
text
input type (even though the renderedtype
attribute markup shows the requested type) - No testing is performed to see if the requested input type is supported by the browser
- Chrome lost support for
datetime
in version 26, Opera in version 15, and Safari in iOS 7 Instead of usingdatetime
, since support should be deprecated, usedate
andtime
as two separate inputs date
andtime
inputs are native browser types, and are not a custom date/time picker- For date and time style inputs, where supported, the displayed value in the GUI may be different from what is returned by its value (i.e. ordering of year-month-date)
- Regardless of input type, the value is always returned as a string representation
v-model.lazy
is not supported byBFormInput
(nor any custom Vue component). Use thelazy
prop insteadv-model
modifiers.number
and.trim
can cause unexpected cursor jumps when the user is typing (this is a Vue issue withv-model
on custom components). Avoid using these modifiers. Use thenumber
ortrim
props instead- Older version of Firefox may not support
readonly
forrange
type inputs - Input types that do not support
min
,max
andstep
(i.e.text
,password
,tel
,email
,url
, etc.) will silently ignore these values (although they will still be rendered on the input markup) if values are provided
Caveats with predictive text entry and IME composition entry:
- When using predictive text auto-suggested words, the
v-model
will not update until the auto-suggested word is selected (or a space is typed). If an auto suggested word is not selected, the v-model will update with the current displayed text of the input when the input is blurred - When using IME composition (ie. Chinese, Japanese, etc.), the
v-model
will not update until the IME composition is completed
Inputs with type range
render using Bootstrap v5's .form-range
class. The track (the
background) and thumb (the value) are both styled to appear the same across browsers.
Range inputs have implicit values for min
and max
of 0
and 100
respectively. You may specify
new values for those using the min
and max
props.
<template>
<label for="range-1">Example range with min and max</label>
<BFormInput id="range-1" v-model="rangeValue" type="range" min="0" max="5" />
<div class="mt-2">Value: {{ rangeValue }}</div>
</template>
<script setup lang="ts">
const rangeValue = ref('2')
</script>
By default, range inputs "snap" to integer values. To change this, you can specify a step
value.
In the example below, we double the number of steps by using step="0.5".
<template>
<label for="range-1">Example range with min and max</label>
<BFormInput id="range-1" v-model="rangeValueStep" type="range" min="0" max="5" step="0.5" />
<div class="mt-2">Value: {{ rangeValueStep }}</div>
</template>
<script setup lang="ts">
const rangeValueStep = ref('2')
</script>
Note: Range inputs (as do all input types) return their value as a string. You may need to
convert the value to a native number by using Number(value)
, parseInt(value, 10)
,
parseFloat(value)
, or use the number
prop.
Note: Bootstrap v5 CSS does not include styling for range inputs inside input groups, nor
validation styling on range inputs. However, bootstrap-vue-next includes custom styling to handle these
situations until styling is included in Bootstrap v5.
Set heights using the size
prop to sm
or lg
for small or large respectively.
To control width, place the input inside standard Bootstrap grid column.
Small: Default: Large:<BRow class="my-1">
<BCol sm="2">
<label for="input-small">Small:</label>
</BCol>
<BCol sm="10">
<BFormInput id="input-small" size="sm" placeholder="Enter your name" />
</BCol>
</BRow>
<BRow class="my-1">
<BCol sm="2">
<label for="input-default">Default:</label>
</BCol>
<BCol sm="10">
<BFormInput id="input-default" placeholder="Enter your name" />
</BCol>
</BRow>
<BRow class="my-1">
<BCol sm="2">
<label for="input-large">Large:</label>
</BCol>
<BCol sm="10">
<BFormInput id="input-large" size="lg" placeholder="Enter your name" />
</BCol>
</BRow>
Note: Input type range
currently does not support control sizing unless it is placed inside a
BInputGroup
which has its size
prop set.
Note: The native HTML <input>
attribute size
(which sets a horizontal width on the <input>
in characters) is not supported. Use styling, utility classes, or the layout rows (BRow
) and
columns (BCol
) to set the desired width.
Bootstrap includes validation styles for valid
and invalid
states on most form controls.
Generally speaking, you'll want to use a particular state for specific types of feedback:
false
(denotes invalid state) is great for when there is a blocking or required field. A user must fill in this field properly to submit the formtrue
(denotes valid state) is ideal for situations when you have per-field validation throughout a form and want to encourage a user through the rest of the fieldsnull
Displays no validation state (neither valid nor invalid)
To apply one of the contextual state icons on BFormInput
, set the state
prop to false
(for
invalid), true
(for valid), or null
(no validation state).
<BRow class="my-1">
<BCol sm="3">
<label for="input-none">No State:</label>
</BCol>
<BCol sm="9">
<BFormInput id="input-none" :state="null" placeholder="No validation" />
</BCol>
</BRow>
<BRow class="my-1">
<BCol sm="3">
<label for="input-valid">Valid State:</label>
</BCol>
<BCol sm="9">
<BFormInput id="input-valid" :state="true" placeholder="Valid input" />
</BCol>
</BRow>
<BRow class="my-1">
<BCol sm="3">
<label for="input-invalid">Invalid State:</label>
</BCol>
<BCol sm="9">
<BFormInput id="input-invalid" :state="false" placeholder="Invalid input" />
</BCol>
</BRow>
<template>
<div role="group">
<label for="input-live">Name:</label>
<BFormInput
id="input-live"
v-model="lifeName"
:state="lifeNameState"
aria-describedby="input-live-help input-live-feedback"
placeholder="Enter your name"
trim
/>
<!-- This will only be shown if the preceding input has an invalid state -->
<BFormInvalidFeedback id="input-live-feedback"> Enter at least 3 letters </BFormInvalidFeedback>
<!-- This is a form text block (formerly known as help block) -->
<BFormText id="input-live-help">Your full name.</BFormText>
</div>
</template>
<script setup lang="ts">
const lifeName = ref('')
const lifeNameState = computed(() => (lifeName.value?.length > 2 ? true : false))
</script>
Tip: Use the
BFormGroup
component to automatically generate markup similar to above.
Using these contextual states to denote the state of a form control only provides a visual, color-based indication, which will not be conveyed to users of assistive technologies - such as screen readers - or to colorblind users.
Ensure that an alternative indication of state is also provided. For instance, you could include a
hint about state in the form control's <label>
text itself, or by providing an additional help
text block.
Specifically for assistive technologies, invalid form controls can also be assigned an
aria-invalid="true"
attribute.
When BFormInput
has an invalid contextual state (i.e. state is false
) you may also want to
set the BFormInput
prop aria-invalid
to true
, or to one of the supported values:
false
: Convey no errors detected (default)true
(or'true'
): Convey that the value has failed validation'grammar'
Convey that a grammatical error has been detected'spelling'
Convey that a spelling error has been detected
If aria-invalid
is not explicitly set and state
is set to false
, then the aria-invalid
attribute on the input will automatically be set to 'true'
;
BFormInput
optionally supports formatting by passing a function reference to the formatter
prop.
Formatting (when a formatter function is supplied) occurs when the control's native input
and
change
events fire. You can use the boolean prop lazy-formatter
to restrict the formatter
function to being called on the control's native blur
event.
The formatter
function receives two arguments: the raw value
of the input element, and the
native event
object that triggered the format (if available).
The formatter
function should return the formatted value as a string.
Formatting does not occur if a formatter
is not provided.
Value: {{ formatInputText }}
Value: {{ formatLazyInputText }}
<template>
<div role="group">
<label for="input-formatter">"Text input with formatter (on input)"</label>
<BFormInput
id="input-formatter"
v-model="formatInputText"
placeholder="Enter your name"
:formatter="toLowerCaseFormatter"
/>
<p><b>Value:</b> {{ formatInputText }}</p>
</div>
<div role="group">
<label for="input-formatter">"Text input with lazy formatter (on blur)"</label>
<BFormInput
id="input-lazy"
v-model="formatLazyInputText"
placeholder="Enter your name"
lazy-formatter
:formatter="toLowerCaseFormatter"
/>
<p><b>Value:</b> {{ formatLazyInputText }}</p>
</div>
</template>
<script setup lang="ts">
const formatInputText = ref('')
const formatLazyInputText = ref('')
const toLowerCaseFormatter = (value: string) => value.toLowerCase()
</script>
Note: When using a non-text-like input (i.e. color
, range
, date
, number
, email
etc.),
ensure that your formatter function returns the value in the expected format (date
->
'2000-06-01', color
-> '#ff0000', etc.) for the input type. The formatter must return the
value as a string.
Note: With non-lazy formatting, if the cursor is not at the end of the input value, the cursor
may jump to the end after a character is typed. You can use the provided event object and the
event.target
to access the native input's selection methods and properties to control where the
insertion point is. This is left as an exercise for the reader.
If you want to have <BFormInput readonly>
elements in your form styled as plain text, set the
plaintext
prop (no need to set readonly
) to remove the default form field styling and preserve
the correct margin and padding.
The plaintext
option is not supported by input types color
or range
.
Vue does not officially support .lazy
, .trim
, and .number
modifiers on the v-model
of custom
component based inputs, and may generate a bad user experience. Avoid using Vue's native modifiers.
To get around this, BFormInput
has three boolean props trim
, number
, and lazy
which
emulate the native Vue v-model
modifiers .trim
and .number
and .lazy
respectively. The
lazy
prop will update the v-model on change
/blur
events.
Notes:
- The
number
prop takes precedence over thetrim
prop (i.e.trim
will have no effect whennumber
is set) - When using the
number
prop, and if the value can be parsed as a number (viaparseFloat
) it will return a value of typeNumber
to thev-model
, otherwise the original input value is returned as typeString
. This is the same behaviour as the native.number
modifier - The
trim
andnumber
modifier props do not affect the value returned by theinput
orchange
events. These events will always return the string value of the content of<textarea>
after optional formatting (which may not match the value returned via thev-model
update
event, which handles the modifiers)
When the autofocus
prop is set, the input will be auto-focused when it is inserted (i.e.
mounted) into the document, or re-activated when inside a Vue KeepAlive
component. Note
that this prop does not set the autofocus
attribute on the input, nor can it tell when the
input becomes visible.
All native events (other than the custom input
and change
events) are supported, without the
need for the .native
modifier.
The custom input
and change
events receive a single argument of the current value
(after any
formatting has been applied), and are triggered by user interaction.
The custom update
event is passed the input value, and is emitted whenever the v-model
needs
updating (it is emitted before input
, change
. and blur
as needed).
You can always access the native input
and change
events by using the .native
modifier.
BFormInput
exposes the native input element on the component reference as a reference with name 'input'.
You can use that reference to access the native properties and methods.
Property | Notes |
---|---|
.selectionStart |
Read/Write |
.selectionEnd |
Read/Write |
.selectionDirection |
Read/Write |
.validity |
Read only |
.validationMessage |
Read only |
.willValidate |
Read only |
Method | Notes |
---|---|
.focus() |
Focus the input |
.blur() |
Remove focus from the input |
.select() |
Selects all text within the input |
.setSelectionRange() |
|
.setRangeText() |
|
.setCustomValidity() |
|
.checkValidity() |
|
.reportValidity() |
Refer to HTMLInputElement for more information on these methods and properties. Support will vary based on input type.
<template>
<div role="group">
<BFormInput ref="inputRef" v-model="sampleInputText" placeholder="Enter your name" />
</div>
<div class="mt-2">
<BButton primary @click="selectAllText">Select all text</BButton>
</div>
</template>
<script setup lang="ts">
// refs are unified in vue3. We need a ref variable with the same as used in the template.
// The variable will be filled up during mount with the reference to custom component.
// inputRef will become the reference to the b-form-input component.
const inputRef = ref<HTMLElement | null>(null)
const sampleInputText = ref('sample text')
// The inner native input is exposed as ref with name "input"
const selectAllText = () => inputRef.value.input.select()
</script>