perf(Checkbox): skip label querySelector when aria-label is provided (#2715)

zernonia · claude · web-flow · commit 39c52df2657f · 2026-06-16T15:27:47.000+08:00
Closes #2318. `CheckboxRoot` resolved a fallback aria-label by running `document.querySelector([for="<id>"])`. The query is now guarded inside the computed so it never runs when an explicit `aria-label` is passed — avoiding hundreds of DOM lookups when rendering many checkboxes (e.g. a data table). Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
diff --git a/packages/core/src/Checkbox/Checkbox.test.ts b/packages/core/src/Checkbox/Checkbox.test.ts
@@ -1,8 +1,10 @@
 import type { DOMWrapper, VueWrapper } from '@vue/test-utils'
 import { mount } from '@vue/test-utils'
-import { afterAll, beforeEach, describe, expect, it } from 'vitest'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { axe } from 'vitest-axe'
+import { nextTick } from 'vue'
 import { handleSubmit } from '@/test'
+import { CheckboxRoot } from '.'
 import Checkbox from './story/_Checkbox.vue'
 import CheckboxGroup from './story/_CheckboxGroup.vue'
 
@@ -62,6 +64,34 @@ describe('given a default Checkbox', () => {
   })
 })
 
+describe('given a Checkbox with an explicit aria-label', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('should not query the DOM for a label', () => {
+    const querySpy = vi.spyOn(document, 'querySelector')
+    const wrapper = mount(CheckboxRoot, {
+      attachTo: document.body,
+      attrs: { 'id': 'with-label', 'aria-label': 'Accept terms' },
+    })
+
+    expect(wrapper.find('button').attributes('aria-label')).toBe('Accept terms')
+    expect(querySpy).not.toHaveBeenCalledWith('[for="with-label"]')
+  })
+
+  it('should query for the associated label when no aria-label is given', async () => {
+    const querySpy = vi.spyOn(document, 'querySelector')
+    mount(CheckboxRoot, {
+      attachTo: document.body,
+      attrs: { id: 'without-label' },
+    })
+    await nextTick()
+
+    expect(querySpy).toHaveBeenCalledWith('[for="without-label"]')
+  })
+})
+
 describe('given a required Checkbox', () => {
   const wrapper = mount({
     components: { Checkbox },
diff --git a/packages/core/src/Checkbox/CheckboxRoot.vue b/packages/core/src/Checkbox/CheckboxRoot.vue
@@ -47,7 +47,7 @@ export const [injectCheckboxRootContext, provideCheckboxRootContext]
 
 <script setup lang="ts" generic="T = boolean">
 import { isEqual } from 'ohash'
-import { computed } from 'vue'
+import { computed, useAttrs } from 'vue'
 import { Primitive } from '@/Primitive'
 import { RovingFocusItem } from '@/RovingFocus'
 import { VisuallyHiddenInput } from '@/VisuallyHidden'
@@ -122,9 +122,16 @@ function handleClick() {
 }
 
 const isFormControl = useFormControl(currentElement)
-const ariaLabel = computed(() => props.id && currentElement.value
-  ? (document.querySelector(`[for="${props.id}"]`) as HTMLLabelElement)?.innerText
-  : undefined)
+const attrs = useAttrs()
+const ariaLabel = computed(() => {
+  // An explicit `aria-label` always wins, so skip the (potentially expensive)
+  // label lookup entirely — this matters when rendering many checkboxes at once.
+  if (attrs['aria-label'])
+    return undefined
+  return props.id && currentElement.value
+    ? (document.querySelector(`[for="${props.id}"]`) as HTMLLabelElement)?.innerText
+    : undefined
+})
 
 provideCheckboxRootContext({
   disabled,
