Tooltip

A tooltip is a brief message that shows up when a user hovers over a specific part of the user interface, providing additional information.

Guidelines

When to use tooltips

Use the Tooltip component to add a small piece of information to its associated element. Tooltips can be used to explain the meaning or purpose of interface elements like icons and buttons where the initial element might not be clear, or to show the full version of truncated text where space is not available.

Specifications

The Tooltip component includes text-only content.

Component limitations

The minimum width for the Tooltip component is set at @size-125 (equivalent to 24px in the default Codex theme). The maximum width is set at @size-600 (equivalent to 256px).

Refer to the Tooltip component in Codex Figma.

Types

By default, the Tooltip appears beneath its trigger, but automatically moves based on the placement of the trigger and the edge of the viewport. The default placement can be set to one of four options:

1. Bottom
2. Top
3. Right
4. Left

Interaction states

The Tooltip component is purely informational, and is not inherently interactive. The Tooltip will be shown on hover or focus of its trigger. On touchable screens, the tooltip can be shown by long pressing on the trigger.

Best practices

Consider the following recommendations when working with tooltips.

Usage

Do:

• Use a tooltip to provide further clarification or give additional context and information.

Don't:

• Provide significant details or information, such as errors — tooltips can be easily overlooked.

Contents

Do:

• Use only text within a tooltip.

Don't:

• Include interactive elements like links or buttons within a tooltip.

Content

Tooltips are used to describe visual elements or elaborate on textual elements in as few words as possible. Content for Tooltips should be short and concise.

Do:

• Use punctuation for more than one sentence, or when the truncated text includes punctuation.

Don't:

• Use punctuation when the text consists of just one sentence.

Keyboard navigation

Key	Function
Esc	Dismisses the tooltip.

Demos

Configurable

Name	Value
Props
placement	Choose an option bottom bottom-start bottom-end top top-start top-end right right-start right-end left left-start left-end
textContent
View
Reading direction	Left to right (LTR) Right to left (RTL)

Basic Example

Apply the custom tooltip directive, v-tooltip to a component or native HTML element. When you hover over the component or element, the tooltip displays additional information.

NPM

<template>
	<cdx-button v-tooltip="'This is a tooltip'">
		Button with tooltip
	</cdx-button>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxButton, CdxTooltip } from '@wikimedia/codex';

export default defineComponent( {
	name: 'TooltipBasic',
	components: { CdxButton },
	directives: {
		tooltip: CdxTooltip
	}
} );
</script>

MediaWiki

<template>
	<cdx-button v-tooltip="'This is a tooltip'">
		Button with tooltip
	</cdx-button>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxButton, CdxTooltip } = require( '@wikimedia/codex' );

module.exports = defineComponent( {
	name: 'TooltipBasic',
	components: { CdxButton },
	directives: {
		tooltip: CdxTooltip
	}
} );
</script>

Custom placement

The default placement of the tooltip is bottom. Specify the placement by using an argument in your directive like v-tooltip:top. The top argument places the tooltip on top of the reference element.

The tooltip can appear in the following places:

• bottom, bottom-start, bottom-end
• top, top-start, top-end
• right, right-start, right-end
• left, left-start, left-end

NPM

<template>
	<cdx-button v-tooltip:top="'This is a tooltip'">
		Button with tooltip
	</cdx-button>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxButton, CdxTooltip } from '@wikimedia/codex';

export default defineComponent( {
	name: 'TooltipPlacement',
	components: { CdxButton },
	directives: {
		tooltip: CdxTooltip
	}
} );
</script>

MediaWiki

<template>
	<cdx-button v-tooltip:top="'This is a tooltip'">
		Button with tooltip
	</cdx-button>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxButton, CdxTooltip } = require( '@wikimedia/codex' );

module.exports = defineComponent( {
	name: 'TooltipPlacement',
	components: { CdxButton },
	directives: {
		tooltip: CdxTooltip
	}
} );
</script>

Vue Usage

The Tooltip component is implemented as a Vue.js custom directive. This means that rather than existing as a stand-alone component, it can be added to any component or markup element inside of a Vue.js template.

To use the Tooltip, register it under the directives property instead of the components property:

import { defineComponent } from 'vue';
import { CdxButton, CdxTooltip } from '@wikimedia/codex';

export default defineComponent( {
	name: 'MyComponent',
	components: { CdxButton },
	directives: {
		tooltip: CdxTooltip
	}
} );

In the example above, a directive registered under the name tooltip can be used in templates as v-tooltip.

If the Tooltip directive is needed across multiple components, consider registering it globally when the Vue app is mounted:

import { createApp } from 'vue';
import MyApp from './App.vue';
import { CdxTooltip } from '@wikimedia/codex';

const app = createApp( App )
    .directive( 'tooltip', CdxTooltip )
	.mount( '#my-app' );

Not directly usable on all components

Vue directives work best when they are applied directly on HTML elements inside another component's template, like <button> or <input>.

A directive can also be used on another Vue component, but it will always be applied to the outermost element of that component's own template. The tooltip directive will function as expected when used with the CdxButton component (because the outermost element of that component is a <button> element), but it will not behave correctly when used with the CdxTextInput component (which has a <div> as the outermost element).

Future Codex releases may update components like CdxTextInput so that the tooltip functionality is built-in. See the Vue docs about custom directives for more information about how to work with custom directives.