[Bug Report][4.1.10] focus() is not exposed on VCheckbox, VRadioGroup, VSwitch or VColorInput

[johnleider]

Environment

Vuetify Version: 4.1.10
Vue Version: 3.x
OS: Not specified

Steps to reproduce

1. Put a template ref on a v-checkbox, v-radio-group, v-switch or v-color-input
2. Call ref.value.focus()

<template>
  <v-checkbox ref="checkbox" label="VCheckbox" />
</template>

<script setup>
  import { useTemplateRef, onMounted } from 'vue'

  const checkbox = useTemplateRef('checkbox')

  onMounted(() => checkbox.value.focus())
</script>

Expected Behavior

The control receives focus, as it does on every sibling input — VTextField, VTextarea, VFileInput, VSelect, VAutocomplete, VCombobox, VNumberInput, VDateInput, VSlider, VRangeSlider and VOtpInput all expose a working focus().

Actual Behavior

TypeError: focus is not a function — the method does not exist.

Probed in a real browser against 4.1.10:

[VCheckbox]   typeof focus = undefined | THREW TypeError | exposes: reset, validate, resetValidation, isValid
[VRadioGroup] typeof focus = undefined | THREW TypeError | exposes: reset, validate, resetValidation, isValid
[VSwitch]     typeof focus = undefined | THREW TypeError | exposes: reset, validate, resetValidation, isValid
[VColorInput] typeof focus = undefined | THREW TypeError | exposes: NOTHING
[VTextField]  typeof focus = function  | ok, activeElement = <input type=text> | exposes: focus, blur, reset, validate, resetValidation, isValid

Reproduction Link

https://play.vuetifyjs.com/#...

Other comments

Reported by @userquin in Discord; filed on their behalf. Four separate defects, three sharing one cause.

1–3. VCheckbox, VRadioGroup, VSwitch forward refs to a dead end.

All three end with:

return forwardRefs({}, inputRef)   // inputRef is the VInput wrapper

and VInput's setup returns only { reset, resetValidation, validate, isValid, errorMessages } — no focus, no element. So there is nothing for focus() to resolve to. That matches the probe exactly: the four validation members are present, focus/blur are not.

The fix has a precedent in-repo — VSlider/VRangeSlider:

return forwardRefs({ focus: () => thumbContainerRef.value?.$el.focus() }, inputRef)

For checkbox/switch no DOM query is needed: VSelectionControl already returns { isFocused, input }, where input is the native <input>. VRadioGroup needs group semantics — focus the checked radio, falling back to the first, since that is the group's tab stop.

4. VColorInput exposes nothing at all. Its setup (VColorInput.tsx:76) ends after useRender with no return statement and the file contains no refs, so it wraps a VTextField and discards that component's entire public API — not only focus() but reset(), validate(), resetValidation(), isValid and errorMessages. VDateInput and VNumberInput are the same wrapper shape and do forwardRefs({}, vTextFieldRef); one line would fix all of it.

Related: VRadioGroup does not emit update:focused. VCheckbox (:44) and VSwitch (:87) both declare it; VRadioGroup does not, so there is no way to observe its focus state either.

Related: programmatic focus cannot restore the focus ring. VSelectionControl gates .v-selection-control--focus-visible (VSelectionControl.sass:96) on the JS flag isFocusVisible (VSelectionControl.tsx:267), which is only ever set inside onFocus (:192-199). Calling .focus() on an already-focused input fires no focus event, so the ring never reappears — even with focus({ focusVisible: true }). If the new focus() accepts FocusOptions, it should set isFocusVisible directly when options.focusVisible is true rather than infer it from the event. The browser heuristic should stay in place for user-initiated focus; this is only about making an explicit programmatic call authoritative.

Source references

• packages/vuetify/src/components/VCheckbox/VCheckbox.tsx:101
• packages/vuetify/src/components/VRadioGroup/VRadioGroup.tsx:139
• packages/vuetify/src/components/VSwitch/VSwitch.tsx:303
• packages/vuetify/src/components/VColorInput/VColorInput.tsx:76
• packages/vuetify/src/components/VInput/VInput.tsx:263-269
• packages/vuetify/src/components/VSelectionControl/VSelectionControl.tsx:192-199, :267, :330
• packages/vuetify/src/components/VSlider/VSlider.tsx — the pattern to copy

[johnleider]

Adding browser-support data for focus({ focusVisible: true }), courtesy of @userquin — it strengthens the case for handling this in JS rather than delegating to the platform.

HTMLElement.focus: options.focusVisible sits at ~84.5% global support. Firefox has had it since 104, but Chrome/Edge only from 145 and Safari from 18.4. So roughly one user in six is on a browser that silently ignores the option.

That matters because of how isFocusVisible is currently derived (VSelectionControl.tsx:192-199):

if (matchesSelector(e.target as HTMLElement, ':focus-visible') !== false) {
  isFocusVisible.value = true
}

and matchesSelector (util/helpers.ts:713-725) returns null when the selector is unsupported, boolean otherwise — so !== false deliberately fails open for browsers too old to know :focus-visible at all.

The gap is that :focus-visible the selector is far better supported than focusVisible the option. On, say, Chrome 144 the selector is supported, so matchesSelector returns a real answer — and for a scripted focus whose focusVisible hint was ignored, that answer is false. The condition fails, isFocusVisible stays false, no ring. The one case the fail-open branch was written for is the one case that no longer applies.

So delegating to el.focus(options) and hoping the browser honours it would give ~84.5% of users a focus ring and ~15% nothing, with no diagnostic. If the exposed focus(options) instead sets isFocusVisible directly from options.focusVisible, Vuetify's own ring works everywhere, because the class is Vuetify's to set — the platform support question stops mattering entirely.

To be clear about scope: this is only for explicit programmatic focus. The existing matchesSelector heuristic should stay exactly as it is for user-initiated focus, so mouse clicks keep not painting a ring.

[johnleider]

Scoping: the fix is a multi-layer forward, not a one-line change

Raised by @userquin — worth recording, because the shape of the fix isn't obvious from the symptom and it affects how this should be split up.

focus() cannot simply be added to VCheckbox, because the two things it needs — the native <input> and the isFocusVisible flag — both live three layers down, and every intermediate component returns {}:

Layer	current return	has what we need
VCheckbox / VSwitch	forwardRefs({}, inputRef) → VInput	✗ (VInput exposes validation only)
VCheckboxBtn	return {}	✗
VSelectionControlGroup	return {}	✗
VSelectionControl	{ isFocused, input }	✓ input (native element) and isFocusVisible (internal)

So the chain has to be reconnected at each hop.

⚠️ useFocus does not move focus

VCheckbox:49 and VSwitch:96 both destructure:

const { isFocused, focus, blur } = useFocus(props)

That focus is a state setter backing update:focused — it sets a boolean and never touches the DOM. Writing forwardRefs({ focus }, inputRef) would compile, expose something callable, and silently do nothing to focus. Alias those bindings before exposing anything named focus.

(VRadioGroup doesn't call useFocus at all, which is also why it never emits update:focused — see the original report.)

Minimum viable chain

1. VSelectionControl — add to its existing return:

   function focus (options?: FocusOptions) {
     input.value?.focus(options)
     if (options?.focusVisible !== undefined) isFocusVisible.value = options.focusVisible
   }
   return { isFocused, input, focus }

2. VCheckboxBtn — return {} → ref its VSelectionControl and forwardRefs({}, controlRef)
3. VCheckbox / VSwitch — ref the btn and forward, aliasing the useFocus bindings
4. VSelectionControlGroup — expose focus(options) that delegates to the checked control, falling back to the first (that's the group's real tab stop)
5. VRadioGroup — forward to the group

This splits cleanly into two PRs

The two halves are independent, and the first is much smaller:

• Fix the bug — wire input.focus(options) through the chain. .focus() stops throwing and focus lands. Resolves the reported issue on its own.
• Fix the ring — the isFocusVisible override, per the support-data comment above.

VColorInput is independent of both and is genuinely one line — forwardRefs({}, vTextFieldRef), matching VDateInput/VNumberInput. That restores focus() and the reset() / validate() / resetValidation() / isValid / errorMessages it currently discards. Cheapest fix in the set; no reason for it to wait on the rest.

Why this keeps happening

Every layer here renders correct markup and drops the imperative surface on the floor. VTextField forwards three refs and lands on the native input; the selection-control family forwards one that dead-ends at a validation API. Nothing catches that, because nothing tests what these components expose — the same gap being tracked for v0 in vuetifyjs/0#926.