Naive UI Tooltip Component

Tooltip component for displaying contextual information, hints, and additional details on hover or focus.

When to Use

Use this component when:

Contextual hints: Provide additional information about elements
Form labels: Show help text for form fields
Icon explanations: Explain icon button functionality
Truncated text: Show full text for truncated content

When to Invoke

Invoke this skill when:

User needs to display tooltip hints
User wants to show contextual help text
User needs different trigger modes
User wants to customize tooltip placement
User asks about hover/focus information display

Features

Multiple Triggers: hover, click, focus, or manual
Placement Options: 12 placement positions
Arrow Control: Show or hide tooltip arrow
Custom Styling: Apply custom styles to tooltip body
Event Handling: Respond to show/hide events

API Reference

Tooltip Props

See Popover Props for full API reference. Key props include:

Name	Type	Default	Description
trigger	`'hover' \| 'click' \| 'focus' \| 'manual'`	`'hover'`	Trigger mode.
placement	`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'`	`'top'`	Tooltip placement.
show	`boolean`	`false`	Whether to show tooltip (manual mode).
show-arrow	`boolean`	`true`	Whether to show arrow.
style	`string \| Object`	`undefined`	Tooltip body style.
disabled	`boolean`	`false`	Whether to disable tooltip.
delay	`number`	`0`	Delay in milliseconds before showing.
duration	`number`	`100`	Duration in milliseconds before hiding.

Tooltip Slots

Name	Parameters	Description
default	`()`	Tooltip content.
trigger	`()`	Element that triggers the tooltip.

Tooltip Events

Name	Parameters	Description
update:show	`(show: boolean)`	Callback when tooltip visibility changes.

Basic Usage

Basic Tooltip

<template>
  <n-tooltip trigger="hover">
    <template #trigger>
      <n-button>Hover Me</n-button>
    </template>
    This is a tooltip
  </n-tooltip>
</template>

Different Triggers

<template>
  <n-space>
    <n-tooltip placement="bottom" trigger="hover">
      <template #trigger>
        <n-button>Hover</n-button>
      </template>
      Hover tooltip
    </n-tooltip>
    
    <n-tooltip placement="bottom" trigger="click">
      <template #trigger>
        <n-button>Click</n-button>
      </template>
      Click tooltip
    </n-tooltip>
    
    <n-tooltip placement="bottom" trigger="focus">
      <template #trigger>
        <n-input placeholder="Focus me" />
      </template>
      Focus tooltip
    </n-tooltip>
  </n-space>
</template>

Placement Options

<template>
  <n-space>
    <n-tooltip placement="top-start" trigger="hover">
      <template #trigger>
        <n-button>Top Start</n-button>
      </template>
      Tooltip content
    </n-tooltip>
    
    <n-tooltip placement="bottom" trigger="hover">
      <template #trigger>
        <n-button>Bottom</n-button>
      </template>
      Tooltip content
    </n-tooltip>
    
    <n-tooltip placement="left" trigger="hover">
      <template #trigger>
        <n-button>Left</n-button>
      </template>
      Tooltip content
    </n-tooltip>
    
    <n-tooltip placement="right" trigger="hover">
      <template #trigger>
        <n-button>Right</n-button>
      </template>
      Tooltip content
    </n-tooltip>
  </n-space>
</template>

No Arrow

<template>
  <n-tooltip trigger="hover" :show-arrow="false">
    <template #trigger>
      <n-button>No Arrow</n-button>
    </template>
    Tooltip without arrow
  </n-tooltip>
</template>

Custom Style

<template>
  <n-tooltip :style="{ maxWidth: '400px' }" trigger="click">
    <template #trigger>
      <n-button>Wide Tooltip</n-button>
    </template>
    This is a very long tooltip content that will wrap to multiple lines when it exceeds the maximum width.
  </n-tooltip>
</template>

Common Patterns

Icon Button Tooltip

<template>
  <n-space>
    <n-tooltip trigger="hover">
      <template #trigger>
        <n-button circle>
          <template #icon>
            <n-icon><SettingsOutline /></n-icon>
          </template>
        </n-button>
      </template>
      Settings
    </n-tooltip>
    
    <n-tooltip trigger="hover">
      <template #trigger>
        <n-button circle>
          <template #icon>
            <n-icon><TrashOutline /></n-icon>
          </template>
        </n-button>
      </template>
      Delete
    </n-tooltip>
  </n-space>
</template>

<script setup>
import { SettingsOutline, TrashOutline } from '@vicons/ionicons5'
</script>

Form Field Help

<template>
  <n-form-item>
    <template #label>
      <n-space align="center" :size="4">
        <span>Password</span>
        <n-tooltip trigger="hover">
          <template #trigger>
            <n-icon size="16" style="cursor: help;">
              <HelpCircleOutline />
            </n-icon>
          </template>
          Password must be at least 8 characters with uppercase, lowercase, and numbers
        </n-tooltip>
      </n-space>
    </template>
    <n-input type="password" v-model:value="password" />
  </n-form-item>
</template>

<script setup>
import { ref } from 'vue'
import { HelpCircleOutline } from '@vicons/ionicons5'

const password = ref('')
</script>

Truncated Text Tooltip

<template>
  <n-tooltip trigger="hover" :style="{ maxWidth: '300px' }">
    <template #trigger>
      <n-ellipsis style="max-width: 200px;">
        {{ longText }}
      </n-ellipsis>
    </template>
    {{ longText }}
  </n-tooltip>
</template>

<script setup>
const longText = 'This is a very long text that will be truncated and shown in tooltip on hover.'
</script>

Event Handling

<template>
  <n-space vertical>
    <n-tooltip
      placement="bottom"
      trigger="hover"
      @update:show="handleUpdateShow"
    >
      <template #trigger>
        <n-button>Hover and Check Console</n-button>
      </template>
      Tooltip content
    </n-tooltip>
    <n-text>Tooltip is: {{ visible ? 'visible' : 'hidden' }}</n-text>
  </n-space>
</template>

<script setup>
import { ref } from 'vue'

const visible = ref(false)

const handleUpdateShow = (show) => {
  visible.value = show
  console.log('Tooltip visibility:', show)
}
</script>

Manual Control

<template>
  <n-space vertical>
    <n-tooltip v-model:show="show" trigger="manual" placement="right">
      <template #trigger>
        <n-input v-model:value="value" placeholder="Type something" />
      </template>
      Press Enter to confirm
    </n-tooltip>
    <n-button @click="show = !show">Toggle Tooltip</n-button>
  </n-space>
</template>

<script setup>
import { ref, watch } from 'vue'

const show = ref(false)
const value = ref('')

watch(value, (newVal) => {
  show.value = newVal.length > 0
})
</script>

Rich Content Tooltip

<template>
  <n-tooltip trigger="hover" :style="{ maxWidth: '250px' }">
    <template #trigger>
      <n-button type="primary">User Info</n-button>
    </template>
    <div>
      <n-text strong>John Doe</n-text>
      <br />
      <n-text depth="3">john@example.com</n-text>
      <n-divider style="margin: 8px 0;" />
      <n-text>Last login: 2 hours ago</n-text>
    </div>
  </n-tooltip>
</template>

Table Cell Tooltip

<template>
  <n-data-table :columns="columns" :data="data" />
</template>

<script setup>
import { h } from 'vue'
import { NTooltip, NButton } from 'naive-ui'

const columns = [
  {
    title: 'Name',
    key: 'name',
    render(row) {
      return h(NTooltip, {
        trigger: 'hover'
      }, {
        trigger: () => h('span', { style: 'cursor: pointer;' }, row.name),
        default: () => `Full name: ${row.fullName}`
      })
    }
  },
  { title: 'Age', key: 'age' }
]

const data = [
  { name: 'John', fullName: 'John Doe', age: 25 },
  { name: 'Jane', fullName: 'Jane Smith', age: 30 }
]
</script>

Delayed Tooltip

<template>
  <n-space>
    <n-tooltip trigger="hover" :delay="500">
      <template #trigger>
        <n-button>Delayed (500ms)</n-button>
      </template>
      This tooltip appears after 500ms delay
    </n-tooltip>
    
    <n-tooltip trigger="hover" :duration="1000">
      <template #trigger>
        <n-button>Long Duration (1000ms)</n-button>
      </template>
      This tooltip stays for 1000ms after mouse leave
    </n-tooltip>
  </n-space>
</template>

Disabled Tooltip

<template>
  <n-space vertical>
    <n-switch v-model:value="enabled" />
    <n-tooltip trigger="hover" :disabled="!enabled">
      <template #trigger>
        <n-button>Hover Me</n-button>
      </template>
      Tooltip is {{ enabled ? 'enabled' : 'disabled' }}
    </n-tooltip>
  </n-space>
</template>

<script setup>
import { ref } from 'vue'

const enabled = ref(true)
</script>

Best Practices

Keep content concise: Tooltips should be brief
```
<n-tooltip>Short, helpful text</n-tooltip>
```

Use appropriate triggers: Match trigger to use case

<n-tooltip trigger="hover"> <!-- For quick hints -->
<n-tooltip trigger="click"> <!-- For detailed info -->

Position wisely: Place tooltip where it won't obstruct

<n-tooltip placement="top"> <!-- For buttons -->
<n-tooltip placement="right"> <!-- For sidebar items -->

Hide arrow for cleaner look: When appropriate
```
<n-tooltip :show-arrow="false" />
```
Add delay for hover tooltips: Prevent accidental triggers
```
<n-tooltip :delay="200" />
```
Limit width for long content: Prevent overly wide tooltips
```
<n-tooltip :style="{ maxWidth: '300px' }" />
```

Don't use for critical info: Tooltips may not be seen

<!-- Bad: Critical info in tooltip -->
<!-- Good: Critical info visible, tooltip for extra context -->

n-tooltip

SKILL.mdcomponents/n-tooltip/SKILL.md