[Documentation] Docs for VInput, VField, and custom inputs in general are very lacking

Problem to solve

I'm using Vuetify 3.9.5.

I've made several attempts to create custom inputs, using VInput (and friends, such as VField). Every time, I've been unable to figure out how these components are supposed to work, and have been forced to give up.

I've been working with Vuetify for three years. I know its conventions pretty well by now. This shouldn't be this hard.

Specific points of confusion:

Using components other than VInput in the examples is confusing

In the main docs for VInput, many of the examples replace VInput with other components (e.g., VTextField), and leave it up to me to "fill in the blanks".

This obscures more than it illuminates. I already know how to use VTextField. I want to know how to use VInput.

How should the <v-input label="" /> prop be used?

The API docs for VInput indicate that it has a label prop (and this prop does exist in the code). However:

• This prop isn't mentioned in the component's main docs. Why not?
• In my experimentation, the prop doesn't seem to actually do anything. Why not?

How should the <v-input :rules="[]" /> prop be used?

VInput has a rules prop, but it's very unclear how it's meant to be used. On other form components, rules passed to the rules prop are used to validate the modelValue – but VInput doesn't have a modelValue.

So what does the rules prop on VInput do, exactly? The example given is no help at all.

(I see that VTextField – which uses VInput internally – sets a v-model prop on the VInput anyway. Huh?)

Need main (non-API) docs for VField

Self-explanatory. More specific concerns are itemized below.

VField: Floating labels

How do I get the floating label to actually float?

I would expect this to happen automatically when the control receives focus, or when its modelValue is non-empty. But like VInput, VField doesn't have a modelValue prop, and it's unclear how I'm supposed to let VField know when the control has focus (see below).

VField: Why are isActive and isFocused always true? Why don't focus() and blur() seem to do anything?

Consider the following, very basic usage of VField:

  <v-field>
    <template v-slot:default="{ isActive, isFocused, blur, props }">
      <div :id="props.id" :class="props.class" @click="() => { console.log('calling blur()'); blur(); console.log('blur() called') }">
        {{ isFocused ? 'focused' : 'not focused' }} /
        {{ isActive ? 'active' : 'not active' }}
      </div>
    </template>
  </v-field>

• In the browser, this control always reads "focused / active" – even when another control is focused and active! Why?
• I would expect clicking on the div to change isFocused to false, but it doesn't. Why?

Need a basic example of combining VInput with VField

Suppose that I want to create a custom EmployeeField component, as follows:

• It looks exactly like a VTextField.
• The selected employee's name is displayed inside the (either as a readonly <input>, or as plain text).
• Its v-model is an integer (or null, if the field is empty).
• Clicking on the field doesn't focus the <input> (there might not even be an <input> – see above). Instead, it opens a picker inside a menu, which allows the user to search for and select an employee via a simple form.

This is a pretty basic custom field, and I imagine this is a common scenario. However, given all the points of confusion above, I have no idea how to approach this. I've experimented extensively, and spend plenty of time with the docs, and it's only left me more confused.

Proposed solution

Write documentation.