APG Patterns
English GitHub
English GitHub

Tooltip

要素がキーボードフォーカスを受け取ったとき、またはマウスがその上にホバーしたときに、その要素に関連する情報を表示するポップアップ。

🤖 AI Implementation Guide

デモ

アクセシビリティ

WAI-ARIA ロール

WAI-ARIA ステート & プロパティ

aria-describedby

トリガー要素にアクセシブルな説明を提供するために、ツールチップ要素を参照します。

適用先 トリガー要素(ラッパー)
タイミング ツールチップが表示されている時のみ
参照 aria-describedby (opens in new tab)

aria-hidden

ツールチップが支援技術から隠されているかどうかを示します。

true(非表示)| false(表示)
デフォルト true
参照 aria-hidden (opens in new tab)

キーボードサポート

キー アクション
Escape ツールチップを閉じる
Tab 標準のフォーカスナビゲーション。トリガーがフォーカスを受け取るとツールチップが表示される

フォーカス管理

  • ツールチップはフォーカスを受け取らない - APGに従い、ツールチップはフォーカス可能であってはいけません。インタラクティブなコンテンツが必要な場合は、DialogまたはPopoverパターンを使用してください。
  • フォーカスが表示をトリガーする - トリガー要素がフォーカスを受け取ると、設定された遅延後にツールチップが表示されます。
  • ぼかしがツールチップを非表示にする - フォーカスがトリガー要素を離れると、ツールチップは非表示になります。

マウス/ポインター動作

  • ホバーが表示をトリガーする - ポインターをトリガー上に移動すると、遅延後にツールチップが表示されます。
  • ポインター離脱で非表示 - ポインターをトリガーから離すと、ツールチップが非表示になります。

重要な注意事項

注意: APG Tooltipパターンは現在WAIによって「作業中」とマークされています。この実装は文書化されたガイドラインに従っていますが、仕様は進化する可能性があります。 View APG Tooltip Pattern (opens in new tab)

ビジュアルデザイン

この実装は、ツールチップの視認性のベストプラクティスに従っています:

  • 高コントラスト - 暗い背景に明るいテキストで可読性を確保
  • ダークモード対応 - ダークモードで色が適切に反転
  • トリガーの近くに配置 - ツールチップはトリガー要素に隣接して表示
  • 設定可能な遅延 - カーソル移動中の誤作動を防止

ソースコード

Tooltip.vue
<script setup lang="ts">
import { ref, computed, onMounted, onUnmounted, watch } from 'vue';
import { cn } from '@/lib/utils';

export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';

export interface TooltipProps {
  /** Tooltip content */
  content: string;
  /** Controlled open state */
  open?: boolean;
  /** Default open state (uncontrolled) */
  defaultOpen?: boolean;
  /** Delay before showing tooltip (ms) */
  delay?: number;
  /** Tooltip placement */
  placement?: TooltipPlacement;
  /** Custom tooltip ID for SSR */
  id?: string;
  /** Whether the tooltip is disabled */
  disabled?: boolean;
  /** Additional class name for the wrapper */
  class?: string;
  /** Additional class name for the tooltip content */
  tooltipClass?: string;
}

const props = withDefaults(defineProps<TooltipProps>(), {
  open: undefined,
  defaultOpen: false,
  delay: 300,
  placement: 'top',
  id: undefined,
  disabled: false,
  class: '',
  tooltipClass: '',
});

const emit = defineEmits<{
  'update:open': [value: boolean];
}>();

// Generate unique ID
let uid = '';
onMounted(() => {
  uid = props.id ?? `tooltip-${crypto.randomUUID().slice(0, 8)}`;
  tooltipId.value = uid;
});

const tooltipId = ref(props.id ?? '');

const internalOpen = ref(props.defaultOpen);
const isControlled = computed(() => props.open !== undefined);
const isOpen = computed(() => (isControlled.value ? props.open : internalOpen.value));

let timeout: ReturnType<typeof setTimeout> | null = null;

const setOpen = (value: boolean) => {
  if (!isControlled.value) {
    internalOpen.value = value;
  }
  emit('update:open', value);
};

const showTooltip = () => {
  if (props.disabled) return;
  if (timeout) {
    clearTimeout(timeout);
  }
  timeout = setTimeout(() => {
    setOpen(true);
  }, props.delay);
};

const hideTooltip = () => {
  if (timeout) {
    clearTimeout(timeout);
    timeout = null;
  }
  setOpen(false);
};

const handleKeyDown = (event: KeyboardEvent) => {
  if (event.key === 'Escape' && isOpen.value) {
    hideTooltip();
  }
};

watch(isOpen, (newValue) => {
  if (newValue) {
    document.addEventListener('keydown', handleKeyDown);
  } else {
    document.removeEventListener('keydown', handleKeyDown);
  }
});

onUnmounted(() => {
  if (timeout) {
    clearTimeout(timeout);
  }
  document.removeEventListener('keydown', handleKeyDown);
});

const placementClasses: Record<TooltipPlacement, string> = {
  top: 'bottom-full left-1/2 -translate-x-1/2 mb-2',
  bottom: 'top-full left-1/2 -translate-x-1/2 mt-2',
  left: 'right-full top-1/2 -translate-y-1/2 mr-2',
  right: 'left-full top-1/2 -translate-y-1/2 ml-2',
};
</script>

<template>
  <span
    :class="cn('apg-tooltip-trigger', 'relative inline-block', props.class)"
    @mouseenter="showTooltip"
    @mouseleave="hideTooltip"
    @focusin="showTooltip"
    @focusout="hideTooltip"
    :aria-describedby="isOpen && !disabled ? tooltipId : undefined"
  >
    <slot />
    <span
      :id="tooltipId"
      role="tooltip"
      :aria-hidden="!isOpen"
      :class="
        cn(
          'apg-tooltip',
          'absolute z-50 px-3 py-1.5 text-sm',
          'rounded-md bg-gray-900 text-white shadow-lg',
          'dark:bg-gray-100 dark:text-gray-900',
          'pointer-events-none whitespace-nowrap',
          'transition-opacity duration-150',
          placementClasses[placement],
          isOpen ? 'visible opacity-100' : 'invisible opacity-0',
          props.tooltipClass
        )
      "
    >
      {{ content }}
    </span>
  </span>
</template>

使い方

使用例
<script setup>
import Tooltip from './Tooltip.vue';
</script>

<template>
  <Tooltip
    content="Save your changes"
    placement="top"
    :delay="300"
  >
    <button>Save</button>
  </Tooltip>
</template>

API

プロパティ デフォルト 説明
content string - ツールチップのコンテンツ(必須)
open boolean - 制御された開いた状態(v-model:open)
defaultOpen boolean false デフォルトの開いた状態(非制御)
delay number 300 表示前の遅延時間(ミリ秒)
placement 'top' | 'bottom' | 'left' | 'right' 'top' ツールチップの位置
id string 自動生成 カスタム ID
disabled boolean false ツールチップを無効にする

テスト

テスト概要

ToolチップコンポーネントのテストはAPG準拠要件に基づいて優先度レベルに分類されています。

テストカテゴリ

高優先度: APGコア準拠

テスト APG要件
role="tooltip" が存在する ツールチップコンテナはtooltipロールを持つ必要がある
閉じている時はaria-hidden 非表示のツールチップは支援技術から読み取られてはならない
表示時はaria-describedby トリガーは表示時のみツールチップを参照する必要がある
Escapeキーでツールチップを閉じる キーボードによる解除サポート
フォーカスでツールチップを表示 キーボードアクセシビリティ
ぼかしでツールチップを非表示 フォーカス管理

中優先度: アクセシビリティ検証

テスト WCAG要件
axe違反なし(非表示状態) WCAG 2.1 AA準拠
axe違反なし(表示状態) WCAG 2.1 AA準拠
ツールチップはフォーカス可能ではない APG: ツールチップはフォーカスを受け取ってはならない

低優先度: Props & 拡張性

テスト 機能
placement propで位置を変更 配置のカスタマイズ
disabled propで表示を防ぐ 無効化機能
delay propでタイミングを制御 遅延のカスタマイズ
id propでカスタムIDを設定 SSR/カスタムIDサポート
制御されたopen状態 外部状態制御
onOpenChangeコールバック 状態変更通知
className継承 スタイルのカスタマイズ

テストの実行

# すべてのToolチップテストを実行
npm run test -- tooltip

# 特定のフレームワークのテストを実行
npm run test -- Tooltip.test.tsx    # React
npm run test -- Tooltip.test.vue    # Vue
npm run test -- Tooltip.test.svelte # Svelte
Tooltip.test.vue.ts
import { render, screen, waitFor } from '@testing-library/vue';
import userEvent from '@testing-library/user-event';
import { axe } from 'jest-axe';
import { describe, expect, it, vi } from 'vitest';
import Tooltip from './Tooltip.vue';

describe('Tooltip (Vue)', () => {
  describe('APG: ARIA 属性', () => {
    it('role="tooltip" を持つ', () => {
      render(Tooltip, {
        props: { content: 'This is a tooltip' },
        slots: { default: '<button>Hover me</button>' },
      });
      expect(screen.getByRole('tooltip', { hidden: true })).toBeInTheDocument();
    });

    it('非表示時は aria-hidden が true', () => {
      render(Tooltip, {
        props: { content: 'This is a tooltip' },
        slots: { default: '<button>Hover me</button>' },
      });
      const tooltip = screen.getByRole('tooltip', { hidden: true });
      expect(tooltip).toHaveAttribute('aria-hidden', 'true');
    });

    it('表示時は aria-hidden が false', async () => {
      const user = userEvent.setup();
      render(Tooltip, {
        props: { content: 'This is a tooltip', delay: 0 },
        slots: { default: '<button>Hover me</button>' },
      });
      const trigger = screen.getByRole('button');

      await user.hover(trigger);
      await waitFor(() => {
        const tooltip = screen.getByRole('tooltip');
        expect(tooltip).toHaveAttribute('aria-hidden', 'false');
      });
    });
  });

  describe('APG: キーボード操作', () => {
    it('Escape キーで閉じる', async () => {
      const user = userEvent.setup();
      render(Tooltip, {
        props: { content: 'This is a tooltip', delay: 0 },
        slots: { default: '<button>Hover me</button>' },
      });
      const trigger = screen.getByRole('button');

      await user.hover(trigger);
      await waitFor(() => {
        expect(screen.getByRole('tooltip')).toHaveAttribute('aria-hidden', 'false');
      });

      await user.keyboard('{Escape}');
      await waitFor(() => {
        expect(screen.getByRole('tooltip', { hidden: true })).toHaveAttribute(
          'aria-hidden',
          'true'
        );
      });
    });

    it('フォーカスで表示される', async () => {
      const user = userEvent.setup();
      render(Tooltip, {
        props: { content: 'This is a tooltip', delay: 0 },
        slots: { default: '<button>Hover me</button>' },
      });

      await user.tab();
      await waitFor(() => {
        expect(screen.getByRole('tooltip')).toHaveAttribute('aria-hidden', 'false');
      });
    });
  });

  describe('ホバー操作', () => {
    it('ホバーで表示される', async () => {
      const user = userEvent.setup();
      render(Tooltip, {
        props: { content: 'This is a tooltip', delay: 0 },
        slots: { default: '<button>Hover me</button>' },
      });

      await user.hover(screen.getByRole('button'));
      await waitFor(() => {
        expect(screen.getByRole('tooltip')).toHaveAttribute('aria-hidden', 'false');
      });
    });

    it('ホバー解除で閉じる', async () => {
      const user = userEvent.setup();
      render(Tooltip, {
        props: { content: 'This is a tooltip', delay: 0 },
        slots: { default: '<button>Hover me</button>' },
      });
      const trigger = screen.getByRole('button');

      await user.hover(trigger);
      await waitFor(() => {
        expect(screen.getByRole('tooltip')).toHaveAttribute('aria-hidden', 'false');
      });

      await user.unhover(trigger);
      await waitFor(() => {
        expect(screen.getByRole('tooltip', { hidden: true })).toHaveAttribute(
          'aria-hidden',
          'true'
        );
      });
    });
  });

  describe('アクセシビリティ', () => {
    it('axe による WCAG 2.1 AA 違反がない', async () => {
      const { container } = render(Tooltip, {
        props: { content: 'This is a tooltip' },
        slots: { default: '<button>Hover me</button>' },
      });
      const results = await axe(container);
      expect(results).toHaveNoViolations();
    });

    it('tooltip がフォーカスを受け取らない', () => {
      render(Tooltip, {
        props: { content: 'This is a tooltip' },
        slots: { default: '<button>Hover me</button>' },
      });
      const tooltip = screen.getByRole('tooltip', { hidden: true });
      expect(tooltip).not.toHaveAttribute('tabindex');
    });
  });

  describe('Props', () => {
    it('placement prop で位置を変更できる', () => {
      render(Tooltip, {
        props: { content: 'Tooltip', placement: 'bottom' },
        slots: { default: '<button>Hover me</button>' },
      });
      const tooltip = screen.getByRole('tooltip', { hidden: true });
      expect(tooltip).toHaveClass('top-full');
    });

    it('disabled の場合、tooltip が表示されない', async () => {
      const user = userEvent.setup();
      render(Tooltip, {
        props: { content: 'Tooltip', delay: 0, disabled: true },
        slots: { default: '<button>Hover me</button>' },
      });

      await user.hover(screen.getByRole('button'));
      await new Promise((r) => setTimeout(r, 50));
      expect(screen.getByRole('tooltip', { hidden: true })).toHaveAttribute('aria-hidden', 'true');
    });

    it('id prop でカスタム ID を設定できる', () => {
      render(Tooltip, {
        props: { content: 'Tooltip', id: 'custom-tooltip-id' },
        slots: { default: '<button>Hover me</button>' },
      });
      const tooltip = screen.getByRole('tooltip', { hidden: true });
      expect(tooltip).toHaveAttribute('id', 'custom-tooltip-id');
    });
  });
});

リソース