Tooltip

Tooltipit ovat pieniä ponnahdusikkunoita, jotka tarjoavat lisätietoa muista käyttöliittymäelementeistä.

Tooltipit ovat pieniä ponnahdusikkunoita, jotka tarjoavat lisätietoa muista käyttöliittymäelementeistä. Elementin tooltip tulee näkyviin, kun käyttäjä vie hiiren osoittimen elementin päälle tai kun elementti saa näppäimistön fokuksen.

Open in a
new tab

Source code

TooltipBasic.javapackage com.vaadin.demo.component.tooltip;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.icon.Icon;
import com.vaadin.flow.component.textfield.TextField;
import com.vaadin.flow.router.Route;

@Route("tooltip-basic")
public class TooltipBasic extends Div {

    public TooltipBasic() {
        // tag::snippet[]
        TextField textField = new TextField();
        textField.setPlaceholder("Search");
        textField.setPrefixComponent(new Icon("lumo", "search"));
        textField.setTooltipText("Wrap in “quotes” for exact phrase");
        add(textField);
        // end::snippet[]
    }

}
tooltip-basic.tsximport '@vaadin/vaadin-lumo-styles/vaadin-iconset';
import React from 'react';
import { Icon } from '@vaadin/react-components/Icon.js';
import { TextField } from '@vaadin/react-components/TextField.js';
import { Tooltip } from '@vaadin/react-components/Tooltip.js';

function Example() {
  return (
    // tag::snippet[]
    <TextField placeholder="Search">
      <Icon icon="lumo:search" slot="prefix" />
      <Tooltip slot="tooltip" text="Wrap in “quotes” for exact phrase" />
    </TextField>
    // end::snippet[]
  );
}

tooltip-basic.tsimport '@vaadin/icon';
import '@vaadin/text-field';
import '@vaadin/tooltip';
import '@vaadin/vaadin-lumo-styles/vaadin-iconset.js';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/demo/theme';

@customElement('tooltip-basic')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-text-field placeholder="Search">
        <vaadin-icon slot="prefix" icon="lumo:search"></vaadin-icon>
        <vaadin-tooltip slot="tooltip" text="Wrap in “quotes” for exact phrase"></vaadin-tooltip>
      </vaadin-text-field>
      <!-- end::snippet[] -->
    `;
  }
}

Tooltipit tukevat vain pelkkää tekstiä. Ne eivät ole fokusoitavissa, eivätkä ne voi sisältää interaktiivisia elementtejä.

Muut käyttöliittymäelementit

Tooltip voidaan näyttää käyttöliittymäelementeille, joilta puuttuu oma tooltip-API. Näiden saavutettavuutta ei kuitenkaan voida taata.

Open in a
new tab

Source code

TooltipHtmlElement.javapackage com.vaadin.demo.component.tooltip;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.H2;
import com.vaadin.flow.component.shared.Tooltip;
import com.vaadin.flow.router.Route;

@Route("tooltip-html-element")
public class TooltipHtmlElement extends Div {

    public TooltipHtmlElement() {
        // tag::snippet[]
        H2 heading = new H2("Heading with tooltip");
        Tooltip tooltip = Tooltip.forComponent(heading)
                .withText("This is a tooltip")
                .withPosition(Tooltip.TooltipPosition.TOP_START);
        add(heading);
        // end::snippet[]
    }

}
tooltip-html-element.tsximport React from 'react';
import { Tooltip } from '@vaadin/react-components/Tooltip.js';

function Example() {
  return (
    <>
      {/* tag::snippet[] */}
      <h2 id="heading">Heading with tooltip</h2>
      <Tooltip for="heading" text="This is a tooltip" position="top-start" />
      {/* end::snippet[] */}
    </>
  );
}

tooltip-html-element.tsimport '@vaadin/tooltip';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/demo/theme';

@customElement('tooltip-html-element')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <h2 id="heading">Heading with tooltip</h2>
      <vaadin-tooltip for="heading" text="This is a tooltip" position="top-start"></vaadin-tooltip>
      <!-- end::snippet[] -->
    `;
  }
}

Grid- ja Menu Bar -komponenteilla on omat API:t tooltipien määrittämiseen.

Sijoittelu

Tooltipin oletussijoittelu suhteessa kohde-elementtiin voidaan ohittaa. Tämä voi olla hyödyllistä, jotta tooltip sijoitetaan optimaalisesti eikä peitä muita tärkeitä käyttöliittymäelementtejä, tai pelkästään esteettisistä syistä.

Open in a
new tab

Source code

TooltipPositioning.javapackage com.vaadin.demo.component.tooltip;

import com.vaadin.flow.component.applayout.AppLayout;
import com.vaadin.flow.component.applayout.DrawerToggle;
import com.vaadin.flow.component.icon.VaadinIcon;
import com.vaadin.flow.component.shared.Tooltip.TooltipPosition;
import com.vaadin.flow.component.sidenav.SideNav;
import com.vaadin.flow.component.sidenav.SideNavItem;
import com.vaadin.flow.router.Route;

@Route("tooltip-positioning")
public class TooltipPositioning extends AppLayout {

    public TooltipPositioning() {
        DrawerToggle toggle = new DrawerToggle();

        SideNav nav = getSideNav();
        nav.getStyle().set("margin", "0 var(--vaadin-gap-xs)")
                .set("--vaadin-icon-size", "1.5rem");

        addToDrawer(nav);
        addToNavbar(toggle);

        getElement().getThemeList().add("narrow-drawer");
    }

    private SideNav getSideNav() {
        SideNav sideNav = new SideNav();
        sideNav.addItem(
                createItem(VaadinIcon.DASHBOARD, "Dashboard", "/dashboard"),
                createItem(VaadinIcon.CART, "Orders", "/orders"),
                createItem(VaadinIcon.USER_HEART, "Customers", "/customers"));
        return sideNav;
    }

    private SideNavItem createItem(VaadinIcon viewIcon, String viewName,
            String path) {
        // tag::snippet[]
        SideNavItem item = new SideNavItem(viewName, path, viewIcon.create());
        item.setTooltipText(viewName).withPosition(TooltipPosition.END);
        // end::snippet[]
        return item;
    }

}
tooltip-positioning.tsximport '@vaadin/icons';
import React, { useEffect, useRef } from 'react';
import {
  AppLayout,
  DrawerToggle,
  Icon,
  SideNav,
  type SideNavElement,
  SideNavItem,
  Tooltip,
} from '@vaadin/react-components';
import { patchSideNavNavigation } from '../../side-nav/react/side-nav-helper';

function Example() {
  const sideNavRef = useRef<SideNavElement>(null);

  useEffect(() => {
    if (sideNavRef.current) {
      // Example-specific workaround
      patchSideNavNavigation(sideNavRef.current);
    }
  }, [sideNavRef.current]);

  return (
    <AppLayout theme="narrow-drawer">
      <DrawerToggle slot="navbar" />

      <SideNav
        slot="drawer"
        ref={sideNavRef}
        style={{ margin: '0 var(--vaadin-gap-xs)', '--vaadin-icon-size': '1.5rem' }}
      >
        {/* tag::snippet[] */}
        <SideNavItem path="/dashboard">
          <Icon icon="vaadin:dashboard" slot="prefix" />
          <Tooltip slot="tooltip" text="Dashboard" position="end" />
        </SideNavItem>
        {/* end::snippet[] */}
        <SideNavItem path="/orders">
          <Icon icon="vaadin:cart" slot="prefix" />
          <Tooltip slot="tooltip" text="Orders" position="end" />
        </SideNavItem>
        <SideNavItem path="/customers">
          <Icon icon="vaadin:user-heart" slot="prefix" />
          <Tooltip slot="tooltip" text="Customers" position="end" />
        </SideNavItem>
      </SideNav>
    </AppLayout>
  );
}

tooltip-positioning.tsimport '@vaadin/app-layout';
import '@vaadin/app-layout/vaadin-drawer-toggle.js';
import '@vaadin/icon';
import '@vaadin/icons';
import '@vaadin/side-nav';
import '@vaadin/tooltip';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/demo/theme';

@customElement('tooltip-positioning')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    applyTheme(root);
    return root;
  }


  protected override render() {
    return html`
      <vaadin-app-layout theme="narrow-drawer">
        <vaadin-drawer-toggle slot="navbar"></vaadin-drawer-toggle>
        <vaadin-side-nav
          slot="drawer"
          style="margin: 0 var(--vaadin-gap-xs); --vaadin-icon-size: 1.5rem;"
        >
          <!-- tag::snippet[] -->
          <vaadin-side-nav-item path="/dashboard">
            <vaadin-icon icon="vaadin:dashboard" slot="prefix"></vaadin-icon>
            <vaadin-tooltip slot="tooltip" text="Dashboard" position="end"></vaadin-tooltip>
          </vaadin-side-nav-item>
          <!-- end::snippet[] -->
          <vaadin-side-nav-item path="/orders">
            <vaadin-icon icon="vaadin:cart" slot="prefix"></vaadin-icon>
            <vaadin-tooltip slot="tooltip" text="Orders" position="end"></vaadin-tooltip>
          </vaadin-side-nav-item>
          <vaadin-side-nav-item path="/customers">
            <vaadin-icon icon="vaadin:user-heart" slot="prefix"></vaadin-icon>
            <vaadin-tooltip slot="tooltip" text="Customers" position="end"></vaadin-tooltip>
          </vaadin-side-nav-item>
        </vaadin-side-nav>
      </vaadin-app-layout>
    `;
  }
}

Tooltipin ja kohde-elementin välistä etäisyyttä voidaan myös mukauttaa asettamalla seuraavat CSS-ominaisuudet tooltipille:

--vaadin-tooltip-offset-top
--vaadin-tooltip-offset-bottom
--vaadin-tooltip-offset-start
--vaadin-tooltip-offset-end

Viiveiden määrittäminen

Tooltipien ilmestymisviive voidaan määrittää erikseen hiiren päälläolon ja näppäimistöfokuksen osalta. Tooltipin katoamisviive – kun osoitin poistuu kohde-elementistä – voidaan myös määrittää erikseen. Kun elementti menettää fokuksen, tooltip suljetaan kuitenkin välittömästi, jotta toiseen elementtiin siirtyminen ei aiheuta hämmennystä.

Source code

Javaimport com.vaadin.flow.component.shared.TooltipConfiguration;

// Yleinen viiveasetusten määrittely:
TooltipConfiguration.setDefaultFocusDelay(2000);
TooltipConfiguration.setDefaultHoverDelay(1000);
TooltipConfiguration.setDefaultHideDelay(1000);

// Ylikirjoitetaan tietyn komponentin tooltipin viiveet:
button.setTooltipText("Home").withHoverDelay(500);
Java
tsximport { Tooltip } from '@vaadin/tooltip';

// Yleinen viiveasetusten määrittely:
Tooltip.setDefaultFocusDelay(2000);
Tooltip.setDefaultHoverDelay(1000);
Tooltip.setDefaultHideDelay(1000);

// Ylikirjoitetaan tietyn komponentin tooltipin viiveet:
<Button>
  Click me
  <Tooltip hoverDelay={500} slot="tooltip" text="Home" />
</Button>
tsx
TypeScriptimport { Tooltip } from '@vaadin/tooltip';

// Yleinen viiveasetusten määrittely:
Tooltip.setDefaultFocusDelay(2000);
Tooltip.setDefaultHoverDelay(1000);
Tooltip.setDefaultHideDelay(1000);

// Ylikirjoitetaan tietyn komponentin tooltipin viiveet:
<vaadin-button>
  Click me
  <vaadin-tooltip .hoverDelay=${500} slot="tooltip" text="Home"></vaadin-tooltip>
</vaadin-button>
TypeScript

Manuaalinen käynnistäminen

Tooltipit voidaan määrittää niin, etteivät ne ilmesty automaattisesti hiiren päälläolon tai näppäimistöfokuksen yhteydessä, vaan ne käynnistetään ohjelmallisesti. Näin voidaan toteuttaa niin sanottuja toggletip-toimintoja – tooltippeja, jotka käyttäjä voi näyttää ja piilottaa manuaalisesti.

Open in a
new tab

Source code

TooltipManual.javapackage com.vaadin.demo.component.tooltip;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.button.Button;
import com.vaadin.flow.component.button.ButtonVariant;
import com.vaadin.flow.component.icon.Icon;
import com.vaadin.flow.component.icon.VaadinIcon;
import com.vaadin.flow.component.shared.Tooltip;
import com.vaadin.flow.component.textfield.TextField;
import com.vaadin.flow.router.Route;

@Route("tooltip-manual")
public class TooltipManual extends Div {

    public TooltipManual() {
        TextField textField = new TextField();
        textField.setPlaceholder("Search");
        textField.setPrefixComponent(new Icon("lumo", "search"));
        Button button = new Button(new Icon(VaadinIcon.INFO_CIRCLE));
        button.addThemeVariants(ButtonVariant.TERTIARY);
        button.getStyle().set("padding", "0").set("border", "0")
                .set("min-width", "0").set("height", "1.25rem");
        textField.setSuffixComponent(button);
        // tag::snippet[]
        textField.setTooltipText("Wrap in “quotes” for exact phrase");
        Tooltip tooltip = textField.getTooltip().withManual(true);
        button.addClickListener(event -> {
            tooltip.setOpened(!tooltip.isOpened());
        });
        // end::snippet[]
        add(textField);
    }

}
tooltip-manual.tsximport '@vaadin/icons';
import '@vaadin/vaadin-lumo-styles/vaadin-iconset.js';
import React from 'react';
import { useSignal } from '@vaadin/hilla-react-signals';
import { Button } from '@vaadin/react-components/Button.js';
import { Icon } from '@vaadin/react-components/Icon.js';
import { TextField } from '@vaadin/react-components/TextField.js';
import { Tooltip } from '@vaadin/react-components/Tooltip.js';

function Example() {
  const tooltipOpened = useSignal(false);

  return (
    // tag::snippet[]
    <TextField placeholder="Search">
      <Icon slot="prefix" icon="lumo:search" />
      <Tooltip
        slot="tooltip"
        text="Wrap in “quotes” for exact phrase"
        manual
        opened={tooltipOpened.value}
      />
      <Button
        slot="suffix"
        theme="tertiary"
        style={{ border: 0, padding: 0, minWidth: 0, height: '1.25rem' }}
        onClick={() => {
          tooltipOpened.value = !tooltipOpened.value;
        }}
      >
        <Icon icon="vaadin:info-circle" />
      </Button>
    </TextField>
    // end::snippet[]
  );
}

tooltip-manual.tsimport '@vaadin/icon';
import '@vaadin/icons';
import '@vaadin/text-field';
import '@vaadin/tooltip';
import '@vaadin/vaadin-lumo-styles/vaadin-iconset.js';
import { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/demo/theme';

@customElement('tooltip-manual')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    applyTheme(root);
    return root;
  }

  @state()
  private tooltipOpened = false;

  protected override render() {
    return html`
      <vaadin-text-field placeholder="Search">
        <vaadin-icon slot="prefix" icon="lumo:search"></vaadin-icon>
        <!-- tag::snippet[] -->
        <vaadin-tooltip
          slot="tooltip"
          text="Wrap in “quotes” for exact phrase"
          manual
          .opened="${this.tooltipOpened}"
        ></vaadin-tooltip>
        <vaadin-button
          slot="suffix"
          theme="tertiary"
          style="padding: 0; border: 0; min-width: 0; height: 1.25rem;"
          @click="${() => {
            this.tooltipOpened = !this.tooltipOpened;
          }}"
        >
          <vaadin-icon icon="vaadin:info-circle"></vaadin-icon>
        </vaadin-button>
        <!-- end::snippet[] -->
      </vaadin-text-field>
    `;
  }
}

Markdown

Tooltip voidaan määrittää renderöimään tekstisisältönsä Markdown-muodossa. Tämän ansiosta voidaan käyttää yksinkertaista muotoilua, kuten lihavointia tai kursivointia. Oletuksena tämä ominaisuus ei ole aktiivinen, ja tooltipin sisältö näytetään pelkkänä tekstinä.

Source code

Java// Komponenteille, jotka toteuttavat HasTooltip:
button.setTooltipMarkdown("**Bold** _Italic_ `Code`");

// Muille komponenteille:
Tooltip.forComponent(header).setMarkdown("**Bold** _Italic_ `Code`");
Java
tsx<Button>
  Click me
  <Tooltip markdown slot="tooltip" text="**Bold** _Italic_ `Code`" />
</Button>
tsx
HTML<vaadin-button>
  Click me
  <vaadin-tooltip markdown slot="tooltip" text="**Bold** _Italic_ `Code`"></vaadin-tooltip>
</vaadin-button>
HTML

Note

Markdownin käyttöä ei suositella, jos tooltipin sisällön saavutettavuus on olennaista, sillä renderöidyn HTML-sisällön semantiikkaa (otsikot, listat, …) ei välitetä avustaville teknologioille. Samoin interaktiivinen sisältö, kuten linkit, ei välttämättä ole saavutettavaa. Monimutkaisempaa tai interaktiivista sisältöä varten kannattaa käyttää mieluummin Popover-komponenttia.

Saavutettavuus

Tooltipit liitetään semanttisesti kohde-elementteihinsä linkin aria-describedby-attribuutin avulla, ja ruudunlukijat ilmoittavat niistä, kun elementti saa näppäimistöfokuksen.

Tooltipien oikeaa ilmoittamista ei kuitenkaan voida taata elementeillä, joilla ei ole omaa tooltip-API:a. Tämä johtuu siitä, että aria-describedby-attribuuttien ilmoittaminen riippuu HTML-elementin tyypistä ja role-attribuutista. Lisäksi se vaihtelee eri ruudunlukijoiden välillä. Ruudunlukijoilla testaaminen on hyödyllistä, jotta voidaan varmistaa tooltipien saavutettavuus näissä tapauksissa.

Tooltip-ominaisuus ei tällä hetkellä tue pitkää painallusta kosketusnäytöllisillä laitteilla.

Huomaa, että Vaadin-komponentit ja muut käyttöliittymäelementit eivät oletuksena viittaa tooltipien olemassaoloon millään tavalla. Tämä voi tehdä niiden löytämisestä vaikeaa käyttäjille.

Yleisesti ottaen näkyvät nimilaput ovat aina parempi vaihtoehto kuin tooltipit. Erikseen määritelty näkymätön linkin aria-label-attribuutti tarjoaa yleensä paremman saavutettavuuden kuin tooltip.

Parhaat käytännöt

Tooltippeja tulisi käyttää vain lisätiedon tarjoamiseen, ei kriittisen tiedon välittämiseen. Ne eivät korvaa syötekenttien näkyviä nimilappuja.

Syötekenttäkomponenteissa tooltipit tulisi ottaa käyttöön vasta viimeisenä keinona, jos tarvittavaa tietoa ei voida antaa nimilapussa, helperissa tai paikkamerkkitekstissä.

Liittyvät komponentit

Komponentti	Käyttösuositukset
Popover	Yleiskäyttöinen peittokomponentti, jonka sijainti on sidottu käyttöliittymän elementtiin.

Komponentti

Käyttösuositukset

Popover

Yleiskäyttöinen peittokomponentti, jonka sijainti on sidottu käyttöliittymän elementtiin.

Docs

Docs

Tooltip

Muut käyttöliittymäelementit

Sijoittelu

Viiveiden määrittäminen

Manuaalinen käynnistäminen

Markdown

Saavutettavuus

Parhaat käytännöt

Liittyvät komponentit