Tooltip

The <nys-toggle> component is a reusable wrapper that displays a brief message when a user hovers over or focuses on its wrapped element, offering additional information or context.

IMPORTANT: Unlike tooltip props found on form-related components, <nys-tooltip> is a standalone wrapper. Wrap a single <nys-icon> or <nys-button> manually to add a tooltip.

Copy Code
<nys-tooltip text="I am a tooltip.">
  <nys-button id="button1" name="button1" label="Hover Me"></nys-button>
</nys-tooltip>

Can’t use NYSDS web components in your project? Try using the CSS Variables instead.


Options

Focusable

Use the focusable prop to make non-focusable slotted elements (i.e. <nys-icon>) accessible via keyboard focus.

Hover over the icon

Copy Code
<p>Hover over the icon</p>
<nys-tooltip text="I am a tooltip." focusable>
  <nys-icon name="info" size="3xl"></nys-icon>
</nys-tooltip>

Position

Use the position prop to control where the direction where the tooltip will appear. If no position is provided, the tooltip will automatically choose the best position based on the available space.

Valid positions are: top, bottom, right, left

Hover over the icon

Copy Code
<p>Hover over the icon</p>
<nys-tooltip text="I am a tooltip." position="right" focusable>
  <nys-icon name="info" size="3xl"></nys-icon>
</nys-tooltip>

Inverted

Set the inverted when the tooltip is on a dark background.

Hover over the icon

Copy Code
<p>Hover over the icon</p>
<nys-tooltip text="I am a tooltip." inverted focusable>
  <nys-icon name="info" size="3xl"></nys-icon>
</nys-tooltip>

Usage

When to use this component

  • Use this component to wrap interactive or visual elements like nys-icon or nys-button to provide additional information or context.

When to consider something else

  • When the information is critical for understanding or completing a task. Use inline text instead.
  • When the information is long or includes links or actions. Tooltips should stay simple and passive.

Do

  • Provide brief and helpful content inside the tooltip.
  • Add tooltips to icons that do not have visible labels and require additional context.

Don't

  • Don't use tooltips for information that is vital to task completion.
  • Don't use interactive elements such as links or buttons inside a tooltip.
  • Don't rely on tooltips when you have room to provide more explanation.

Accessibility

The <nys-tooltip> component includes the following accessibility-focused features:

  • Keyboard and mouse support: tooltip appears when users hover with mouse or focus using a keyboard
  • Tooltip uses role="tooltip" for assistive technologies and sets aria-hidden based on internal state based on when tooltip is hidden or showing.
  • Positioning logic: If a position is not manually set, the tooltip will automatically appear in the direction with the most available space.

Properties

Property Type
id String
text String
focusable boolean
inverted boolean
position "top" | "bottom" | "left" | "right"

CSS Variables


Events

Suggest a New Component

Do you have an idea for a new NYSDS web component? Look through the existing proposals in our GitHub discussions board to see if someone already proposed something similar. If not, feel free to submit one.

Edit this page on GitHub (Permissions required)

Last updated: August 22, 2025