The QField component is used to provide common functionality and aspect to form components. It uses :model-value (or v-model if you want to use clearable property) to have knowledge of the model of the component inside. It has support for labels, hints, errors, validation, and comes in a variety of styles and colors.
QField allows you to display any form control (or almost anything as a matter of fact) inside it. Just place your desired content inside the control slot.
Do NOT wrap QInput, QFile or QSelect with QField as these components already inherit QField.
Design
The examples below use dumb content (text) just to show you the design that QField can use. For checking out examples that wrap real components, see the “Basic Features” section.
QField does not (and should not) manage your control slot, so if you use label prop, it might be a good idea to also specify stack-label, otherwise it might overlap your control when QField is not focused.
Overview
For your QField you can use only one of the main designs (filled, outlined, standout, borderless). You cannot use multiple as they are self-exclusive.
Coloring
Standard
Filled
Outlined
Standout
One of the most appropriate use cases for Standout design is in a QToolbar:
Borderless
The borderless design allows you to seamlessly integrate your QField into other components without QField drawing a border around itself or changing its background color:
Rounded design
The rounded prop only works along with Filled, Outlined and Standout designs, as showcased in the example below:
Square borders
The square prop only makes sense along with Filled, Outlined and Standout designs, as showcased in the example below:
Force dark mode
Basic features
Clearable
As a helper, you can use clearable prop so user can reset model to null through an appended icon.
If using clearable you must use v-model or listen on @update:model-value and update the value.
Control types
Anything you place inside the control slot will be used as content of the field. We provide a few examples of controls below.
Most of the form controls always render something visible, so you if you’re using a label then you might want to set it along with stack-label, otherwise the label will overlap the enclosed control.
Prefix and suffix
Custom Label
Using the label slot you can customize the aspect of the label or add special features as QTooltip.
Do not forget to set the label-slot property.
If you want to interact with the content of the label (QTooltip) add the all-pointer-events class on the element in the slot.
Slots with QBtn type “submit”
When placing a QBtn with type “submit” in one of the “before”, “after”, “prepend”, or “append” slots of a QField, QInput or QSelect, you should also add a @click listener on the QBtn in question. This listener should call the method that submits your form. All “click” events in such slots are not propagated to their parent elements.
Loading state
Validation
Internal validation
You can validate QField components with :rules prop. Specify array of embedded rules or your own validators. Your custom validator will be a function which returns true if validator succeeds or String with error message if it doesn’t succeed.
By default, for perf reasons, a change in the rules does not trigger a new validation until the model changes. In order to trigger the validation when rules change too, then use reactive-rules Boolean prop. The downside is a performance penalty (so use it when you really need this only!) and it can be slightly mitigated by using a computed prop as value for the rules (and not specify them inline in the vue template).
This is so you can write convenient rules of shape like:
value => condition || errorMessageFor example:
value => value < 10 || 'Value should be lower'You can reset the validation by calling resetValidation() method on the QField.
If you set lazy-rules, validation triggers when the field loses focus; while an error is displayed, the field re-validates on each change so the error clears as soon as the value becomes valid. A menu or dialog opened from inside the field (a QPopupProxy in the append slot, for instance) keeps the field focused for as long as it is open, so it does not count as losing focus. If lazy-rules is set to ondemand String, then validation will be triggered only when component’s validate() method is manually called or when the wrapper QForm submits itself.
Async rules
Rules can be async too, by using async/await or by directly returning a Promise. If the value changes or the field gets blurred while an async validation is still in flight, the field re-validates once it settles, so the displayed verdict always matches the current value.
Consider coupling async rules with debounce prop to avoid calling the async rules immediately on each keystroke, which might be detrimental to performance.
External validation
You can also use external validation and only pass error and error-message (enable bottom-slots to display this error message).
Depending on your needs, you might connect Regle (our recommended approach) or some other validation library to QField.
You can also customize the slot for error message:
Accessibility v2.25+
QField renders as a native <label> wired through its for attribute to the enclosed control, using a generated SSR-safe id (overridable through the for prop), so clicking the label focuses the control and screen readers announce the field’s name for it. A disabled field carries aria-disabled on the wrapper, and the clear icon shown by clearable is a keyboard-operable button — activated with Enter or Space — with a localized accessible name from the Quasar Language Pack.
Validation errors are announced as they appear: the error message renders with role="alert", and while it is displayed the control also receives aria-invalid together with aria-errormessage and aria-describedby pointing at the message. These references are applied only while the message actually renders, so they never point at a missing element, and an aria-describedby you set yourself is merged with the error reference rather than replaced by it.
When building your own control through the control slot, this wiring is handed to you rather than applied for you: the slot scope exposes id, ariaInvalid, ariaDescribedby and ariaErrormessage, and it is your responsibility to bind them to your focusable element (the third party mask processor examples on the QInput page show :id="id" in action). Also note that the hint text is purely visual — it is not associated with the control through aria-describedby — so if a hint carries essential information, convey it to assistive technology yourself (for instance through your own element referenced by aria-describedby).