Tooltip

A tooltip is a small, informative text that appears when a user hovers over a user interface element.

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, or to show the full version of truncated text.

Specifications

1. Content
   Tooltip content

Component limitations

The maximum width for the Tooltip is set at @size-1600 (256px).

Demos

Configurable

Name	Value
Props
position	bottom top left right
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 position

The default placement of the tooltip is the bottom position. Specify the tooltip's placement by using arguments in your directive like v-tooltip:top. The top argument specifies to position the tooltip on top of the reference element.

The tooltip can be positioned to these values:

• 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: 'TooltipPosition',
	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: 'TooltipPosition',
	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.