--- title: Field --- 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. > [!WARNING] > Do NOT wrap QInput, QFile or QSelect with QField as these components already inherit QField. ## QField API ### Props - `model-value` (any, optional) Model of the component; Either use this property (along with a listener for 'update:model-value' event) OR use v-model directive - `error` (boolean, optional), default `null` Does field have validation errors?; Setting it to a Boolean (even false) reserves the bottom space for the error message so the layout does not shift when the error appears; leave it at null (the default) when not using external validation, or use 'hide-bottom-space' to not reserve the space - `error-message` (string, optional) Validation error message (gets displayed only if 'error' is set to 'true') Examples: `'Username must have at least 5 characters'` - `no-error-icon` (boolean, optional) Hide error icon when there is an error - `rules` (any[], optional) Array of Functions/Strings; If String, then it must be a name of one of the embedded validation rules Examples: - `[val => val.length <= 3 || 'Please use maximum 3 characters']` - `['fulltime']` - `[(val, rules) => rules.email(val) || 'Please enter a valid email address']` - `reactive-rules` (boolean, optional) By default a change in the rules does not trigger a new validation until the model changes; If set to true then a change in the rules will trigger a validation; Has a performance penalty, so use it only when you really need it - `lazy-rules` (boolean | string, optional), default `false` If set to boolean true then it checks validation status against the 'rules' only when field loses focus; while an error is displayed it re-checks on each model change so the error clears as soon as the value becomes valid; If set to 'ondemand' then it will trigger only when component's validate() method is manually called or when the wrapper QForm submits itself Accepts: `true`, `false`, `'ondemand'` - `label` (string, optional) A text label that will “float” up above the input field, once the field gets focus Examples: `'Username'` - `stack-label` (boolean, optional) Label will be always shown above the field regardless of field content (if any) - `hint` (string, optional) Helper (hint) text which gets placed below your wrapped form component Examples: `'Fill in between 3 and 12 characters'` - `hide-hint` (boolean, optional) Hide the helper (hint) text when field doesn't have focus - `prefix` (string, optional) Prefix Examples: `'$'` - `suffix` (string, optional) Suffix Examples: `'@gmail.com'` - `label-color` (string, optional) Color name for the label from the Quasar Color Palette; Overrides the 'color' prop; The difference from 'color' prop is that the label will always have this color, even when field is not focused Examples: `'primary'`, `'teal'`, `'teal-10'` - `color` (string, optional) Color name for component from the Quasar Color Palette Examples: `'primary'`, `'teal'`, `'teal-10'` - `bg-color` (string, optional) Color name for component from the Quasar Color Palette Examples: `'primary'`, `'teal'`, `'teal-10'` - `dark` (boolean, optional), default `null` Notify the component that the background is a dark color - `loading` (boolean, optional) Signals the user a process is in progress by displaying a spinner; Spinner can be customized by using the 'loading' slot. - `clearable` (boolean, optional) Appends clearable icon when a value (not undefined or null) is set; When clicked, model becomes null - `clear-icon` (string, optional) Custom icon to use for the clear button when using along with 'clearable' prop Examples: `'close'` - `filled` (boolean, optional) Use 'filled' design for the field - `outlined` (boolean, optional) Use 'outlined' design for the field - `borderless` (boolean, optional) Use 'borderless' design for the field - `standout` (boolean | string, optional) Use 'standout' design for the field; Specifies classes to be applied when focused (overriding default ones); a text color class in there also colors the content and the decorators Examples: `true`, `'bg-primary text-white'` - `label-slot` (boolean, optional) Enables label slot; You need to set it to force use of the 'label' slot if the 'label' prop is not set - `bottom-slots` (boolean, optional) Enables bottom slots ('error', 'hint', 'counter') - `hide-bottom-space` (boolean, optional) Do not reserve space for hint/error/counter anymore when these are not used; As a result, it also disables the animation for those - `counter` (boolean, optional) Show an automatic counter on bottom right - `rounded` (boolean, optional) Applies a small standard border-radius for a squared shape of the component - `square` (boolean, optional) Remove border-radius so borders are squared; Overrides 'rounded' prop - `dense` (boolean, optional) Dense mode; occupies less space - `item-aligned` (boolean, optional) Match inner content alignment to that of QItem - `disable` (boolean, optional) Put component in disabled mode - `readonly` (boolean, optional) Put component in readonly mode - `autofocus` (boolean, optional) Focus field on initial component render - `for` (string, optional) Used to specify the 'id' of the control and also the 'for' attribute of the label that wraps it; If no 'name' prop is specified, then it is used for this attribute as well Examples: `'myFieldsId'` - `maxlength` (string | number, optional) Specify a max length of model - `tag` (string, optional), default `'label'` *(added v2.13.1)* HTML tag to use Examples: `'div'`, `'label'` ### Computed Props - `hasError` (boolean, optional) Whether the component is in error state ### Methods - `resetValidation(): void` Reset validation status - `validate(value?: any): boolean | Promise` Trigger a validation Params: - `value` (any, optional) Optional value to validate against Returns: `boolean | Promise` True/false if no async rules, otherwise a Promise with the outcome (true -> validation was a success, false -> invalid models detected) Examples: `true`, `validate().then(outcome => { ... })` - `focus(): void` Focus component - `blur(): void` Blur component (lose focus) ### Events - `@update:model-value` Emitted when the model changes, only when used with 'clearable' or the 'control' scoped slot. Params: - `value` (any, required) New model value - `@focus` Emitted when component gets focused Params: - `evt` (Event, optional) JS event object - `@blur` Emitted when component loses focus Params: - `evt` (Event, optional) JS event object - `@clear` When using the 'clearable' property, this event is emitted when the clear icon is clicked Params: - `value` (any, optional) The previous value before clearing it ### Slots - `#default` Field main content - `#prepend` Prepend inner field; Suggestions: QIcon, QBtn - `#append` Append to inner field; Suggestions: QIcon, QBtn - `#before` Prepend outer field; Suggestions: QIcon, QBtn - `#after` Append outer field; Suggestions: QIcon, QBtn - `#label` Slot for label; Used only if 'label-slot' prop is set or the 'label' prop is set; When it is used the text in the 'label' prop is ignored - `#error` Slot for errors; Enabled only if 'bottom-slots' prop is used; Suggestion:
- `#hint` Slot for hint text; Enabled only if 'bottom-slots' prop is used; Suggestion:
- `#counter` Slot for counter text; Enabled only if 'bottom-slots' prop is used; Suggestion:
- `#loading` Override default spinner when component is in loading mode; Use in conjunction with 'loading' prop ### Scoped Slots - `#control` Slot for controls; Suggestion QSlider, QRange, QKnob, ... Scope: - `id` (string, optional) Element id used in the 'for' attribute of the field label. Can be used to link the control to the label Examples: `'qf_363270c0-7a83-62b1-8dcf-6dfd64ee38fa'` - `field` (Element, optional) DOM element of the field - `editable` (boolean, optional) Field is editable - `focused` (boolean, optional) Field has focus - `floatingLabel` (boolean, optional) Field's label is floating - `modelValue` (any, optional) Field's value Examples: `0.241`, `'Text'` - `emitValue` (Function, optional) Function that emits an @input event in the context of the field Function signature: `(value: any) => void` Params: - `value` (any, required) Value to be emitted Examples: `0`, `'Changed text'` - `ariaInvalid` (string, optional) *(added v2.25)* Value for the control's 'aria-invalid' attribute when the field has an error Examples: `'true'` - `ariaDescribedby` (string, optional) *(added v2.25)* Element id for the field error message; Use it for the control's 'aria-describedby' attribute when rendering a custom control Examples: `'qf_363270c0-7a83-62b1-8dcf-6dfd64ee38fa_error'` - `ariaErrormessage` (string, optional) *(added v2.25)* Element id for the field error message; Use it for the control's 'aria-errormessage' attribute when rendering a custom control Examples: `'qf_363270c0-7a83-62b1-8dcf-6dfd64ee38fa_error'` ## Design > [!NOTE] > 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. > [!TIP] > 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. Example "Design Overview": ```vue ``` ### Coloring ```vue ``` ### Standard ```vue ``` ### Filled ```vue ``` ### Outlined ```vue ``` ### Standout ```vue ``` One of the most appropriate use cases for Standout design is in a QToolbar: Example "Standout in QToolbar": ```vue ``` ### 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: ```vue ``` ### Rounded design The `rounded` prop only works along with Filled, Outlined and Standout designs, as showcased in the example below: Example "Rounded": ```vue ``` ### Square borders The `square` prop only makes sense along with Filled, Outlined and Standout designs, as showcased in the example below: ```vue ``` ### Force dark mode ```vue ``` ## Basic features ### Clearable As a helper, you can use `clearable` prop so user can reset model to `null` through an appended icon. > [!IMPORTANT] > If using `clearable` you must use `v-model` or listen on `@update:model-value` and update the value. ```vue ``` ### 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. ```vue ``` > [!TIP] > 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 ```vue ``` ### Custom Label Using the `label` slot you can customize the aspect of the label or add special features as `QTooltip`. > [!IMPORTANT] > 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. ```vue ``` ### Slots with QBtn type "submit" > [!IMPORTANT] > 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 ```vue ``` ## 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. > [!NOTE] > 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: ```js value => condition || errorMessage // example: value => value < 10 || 'Value should be lower' ``` You can reset the validation by calling `resetValidation()` method on the QField. Example "Basic": ```vue ``` Example "Maximum value": ```vue ``` If you set `lazy-rules`, validation triggers when the field loses focus (a `readonly` field included, only a `disable`d field is exempt from validation); 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. Example "Lazy rules": ```vue ``` #### 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. > [!TIP] > Consider coupling async rules with `debounce` prop to avoid calling the async rules immediately on each keystroke, which might be detrimental to performance. ```vue ``` ### External validation You can also use external validation and only pass `error` and `error-message` (enable `bottom-slots` to display this error message). > [!TIP] > Depending on your needs, you might connect [Regle](https://reglejs.dev/) (our recommended approach) or some other validation library to QField. Example "External": ```vue ``` You can also customize the slot for error message: Example "Slot for error message": ```vue ``` ## Accessibility *(v2.25+)* QField renders as a native `