feat(HoverCard): add enableTouch prop for touch devices (#2687)

benjamincanac · web-flow · commit 40232d36dc7e · 2026-06-10T23:21:45.000+08:00
HoverCard ignores touch input by design (Radix parity), so it can't be opened on mobile. Add an opt-in `enableTouch` prop that lets a tap toggle the card open/closed, gated to `pointerType === 'touch'` so hover/mouse behavior is unchanged. Toggle runs on `pointerup` so a scroll gesture (which fires `pointercancel`) won't trigger it. Also clear the pending open timer in `handleDismiss` so a dismiss can't be reopened by a lingering focus/hover open timer. Resolves #1969
diff --git a/docs/content/meta/HoverCardRoot.md b/docs/content/meta/HoverCardRoot.md
@@ -16,6 +16,13 @@
     'required': false,
     'default': 'false'
   },
+  {
+    'name': 'enableTouch',
+    'description': '<p>When <code>true</code>, tapping the trigger on touch devices toggles the hover card open/closed. By default touch interactions are ignored to match pointer hover semantics.</p>\n',
+    'type': 'boolean',
+    'required': false,
+    'default': 'false'
+  },
   {
     'name': 'open',
     'description': '<p>The controlled open state of the hover card. Can be binded as <code>v-model:open</code>.</p>\n',
@@ -56,6 +63,7 @@
 | --- | --- | --- | --- | --- |
 | `closeDelay` | The duration from when the mouse leaves the trigger or content until the hover card closes. | `number` | No | `300` |
 | `defaultOpen` | The open state of the hover card when it is initially rendered. Use when you do not need to control its open state. | `boolean` | No | `false` |
+| `enableTouch` | When true, tapping the trigger on touch devices toggles the hover card open/closed. By default touch interactions are ignored to match pointer hover semantics. | `boolean` | No | `false` |
 | `open` | The controlled open state of the hover card. Can be binded as v-model:open. | `boolean` | No | - |
 | `openDelay` | The duration from when the mouse enters the trigger until the hover card opens. | `number` | No | `700` |
 
diff --git a/packages/core/src/HoverCard/HoverCard.test.ts b/packages/core/src/HoverCard/HoverCard.test.ts
@@ -29,5 +29,61 @@ describe('given a default HoverCard', () => {
     })
   })
 
+  describe('a touch tap on the trigger', () => {
+    it('should not open the hover card by default', async () => {
+      await wrapper.find('a').trigger('pointerup', { pointerType: 'touch' })
+      await sleep(100)
+      expect(wrapper.find('a').attributes('data-state')).toBe('closed')
+    })
+  })
+
   // HoverCard mainly depends on Popper, test for Popper is not required here
 })
+
+describe('given a HoverCard with enableTouch', () => {
+  let wrapper: VueWrapper<InstanceType<typeof HoverCard>>
+  globalThis.ResizeObserver = class ResizeObserver {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+
+  beforeEach(() => {
+    wrapper = mount(HoverCard, { props: { enableTouch: true }, attachTo: document.body })
+  })
+
+  it('should toggle open/closed on touch tap', async () => {
+    const trigger = wrapper.find('a')
+
+    await trigger.trigger('pointerup', { pointerType: 'touch' })
+    await sleep(10)
+    expect(trigger.attributes('data-state')).toBe('open')
+
+    await trigger.trigger('pointerup', { pointerType: 'touch' })
+    await sleep(10)
+    expect(trigger.attributes('data-state')).toBe('closed')
+  })
+
+  it('should ignore non-touch pointers', async () => {
+    const trigger = wrapper.find('a')
+
+    await trigger.trigger('pointerup', { pointerType: 'mouse' })
+    await sleep(10)
+    expect(trigger.attributes('data-state')).toBe('closed')
+  })
+
+  it('should not reopen from a pending focus timer after closing on touch', async () => {
+    const trigger = wrapper.find('a')
+
+    // focus schedules a delayed open (openDelay), then a touch tap opens immediately
+    await trigger.trigger('focus')
+    await trigger.trigger('pointerup', { pointerType: 'touch' })
+    await sleep(10)
+    expect(trigger.attributes('data-state')).toBe('open')
+
+    // closing must cancel the pending open timer so it doesn't reopen
+    await trigger.trigger('pointerup', { pointerType: 'touch' })
+    await sleep(150)
+    expect(trigger.attributes('data-state')).toBe('closed')
+  })
+})
diff --git a/packages/core/src/HoverCard/HoverCardRoot.vue b/packages/core/src/HoverCard/HoverCardRoot.vue
@@ -11,6 +11,8 @@ export interface HoverCardRootProps {
   openDelay?: number
   /** The duration from when the mouse leaves the trigger or content until the hover card closes. */
   closeDelay?: number
+  /** When `true`, tapping the trigger on touch devices toggles the hover card open/closed. By default touch interactions are ignored to match pointer hover semantics. */
+  enableTouch?: boolean
 }
 export type HoverCardRootEmits = {
   /** Event handler called when the open state of the hover card changes. */
@@ -27,6 +29,7 @@ export interface HoverCardRootContext {
   isPointerDownOnContentRef: Ref<boolean>
   isPointerInTransitRef: Ref<boolean>
   triggerElement: Ref<HTMLElement | undefined>
+  enableTouch: Ref<boolean>
 }
 
 export const [injectHoverCardRootContext, provideHoverCardRootContext]
@@ -43,6 +46,7 @@ const props = withDefaults(defineProps<HoverCardRootProps>(), {
   open: undefined,
   openDelay: 700,
   closeDelay: 300,
+  enableTouch: false,
 })
 const emit = defineEmits<HoverCardRootEmits>()
 
@@ -53,7 +57,7 @@ defineSlots<{
   }) => any
 }>()
 
-const { openDelay, closeDelay } = toRefs(props)
+const { openDelay, closeDelay, enableTouch } = toRefs(props)
 
 useForwardExpose()
 const open = useVModel(props, 'open', emit, {
@@ -80,6 +84,7 @@ function handleClose() {
 }
 
 function handleDismiss() {
+  clearTimeout(openTimerRef.value)
   open.value = false
 }
 
@@ -95,6 +100,7 @@ provideHoverCardRootContext({
   isPointerDownOnContentRef,
   isPointerInTransitRef,
   triggerElement,
+  enableTouch,
 })
 </script>
 
diff --git a/packages/core/src/HoverCard/HoverCardTrigger.vue b/packages/core/src/HoverCard/HoverCardTrigger.vue
@@ -25,6 +25,16 @@ function handleLeave() {
     }
   }, 0)
 }
+
+function handleTouch(event: PointerEvent) {
+  if (!rootContext.enableTouch.value || event.pointerType !== 'touch')
+    return
+
+  if (rootContext.open.value)
+    rootContext.onDismiss()
+  else
+    rootContext.onOpenChange(true)
+}
 </script>
 
 <template>
@@ -40,6 +50,7 @@ function handleLeave() {
       data-grace-area-trigger
       @pointerenter="excludeTouch(rootContext.onOpen)($event)"
       @pointerleave="excludeTouch(handleLeave)($event)"
+      @pointerup="handleTouch"
       @focus="rootContext.onOpen()"
       @blur="rootContext.onClose()"
     >
diff --git a/packages/core/src/HoverCard/story/_HoverCard.vue b/packages/core/src/HoverCard/story/_HoverCard.vue
@@ -8,13 +8,18 @@ import {
   HoverCardTrigger,
 } from '..'
 
+withDefaults(defineProps<{ enableTouch?: boolean }>(), {
+  enableTouch: false,
+})
+
 const hoverState = ref(false)
 </script>
 
 <template>
   <HoverCardRoot
     v-model:open="hoverState"
     :open-delay="100"
+    :enable-touch="enableTouch"
   >
     <HoverCardTrigger
       class="inline-block cursor-pointer rounded-full shadow-[hsl(206_22%_7%_/_35%)_0px_10px_38px_-10px,hsl(206_22%_7%_/_20%)_0px_10px_20px_-15px] outline-none focus:shadow-[0_0_0_2px_white]"
