Visão geral da diretiva Angular Tooltip

The igxTooltip and the igxTooltipTarget directives provide us with the ability to create a fully customizable tooltip and attach it to any element on our page. While most tooltips have a limited number of available positions, with the igxTooltipTarget directive we can specify any position we want on the page while keeping it in relation to the target (anchor) and provide various other overlay settings like scroll strategies and custom animations!

Angular Tooltip Example

Getting Started with Ignite UI for Angular Tooltip

Para começar a usar a diretiva Ignite UI for Angular Tooltip, primeiro você precisa instalar Ignite UI for Angular. Em um aplicativo Angular existente, digite o seguinte comando:

ng add igniteui-angular

Para obter uma introdução completa ao Ignite UI for Angular, leia o tópico de introdução.

O próximo passo é importar issoIgxTooltipModule no seu arquivo app.module.ts.

// app.module.ts

...
import { IgxTooltipModule } from 'igniteui-angular';
// import { IgxTooltipModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    ...
    imports: [IgxTooltipModule],
})
export class AppModule {}

Alternativamente,16.0.0 você pode importarIgxTooltipDirective como uma dependência independente ou usar oIGX_TOOLTIP_DIRECTIVES token para importar o componente e todos os seus componentes e diretivas de suporte.

// home.component.ts

import { IGX_TOOLTIP_DIRECTIVES, IgxAvatarComponent } from 'igniteui-angular';
// import { IGX_TOOLTIP_DIRECTIVES, IgxAvatarComponent } from '@infragistics/igniteui-angular'; for licensed package

@Component({
  selector: 'app-home',
  template: `
    <igx-avatar
      class="avatar"
      #target="tooltipTarget"
      [igxTooltipTarget]="tooltipRef"
      src="assets/images/avatar/10.jpg"
      size="medium"
      shape="circle"
    >
    </igx-avatar>

    <div #tooltipRef="tooltip" igxTooltip>Her name is Madelyn James</div>
  `,
  styleUrls: ['home.component.scss'],
  standalone: true,
  imports: [IGX_TOOLTIP_DIRECTIVES, IgxAvatarComponent],
  /* or imports: [IgxTooltipDirective, IgxTooltipTargetDirective, IgxAvatarComponent] */
})
export class HomeComponent {}

Now that you have the Ignite UI for Angular Tooltip module or directives imported, you can start using the igxTooltip directive.

Using the Angular Tooltip

Let's say we want to create a simple text tooltip like the one above. In our case, we're using our awesome IgxAvatar as the element, so we start by importing the IgxAvatarModule first.

// app.module.ts

import { IgxTooltipModule, IgxAvatarModule } from 'igniteui-angular';
// import { IgxTooltipModule, IgxAvatarModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    ...
    imports: [IgxTooltipModule, IgxAvatarModule],
})
export class AppModule {}

Tooltip target

The avatar will be our target and all we have to do is set the igxTooltipTarget directive on it, which basically marks our element as one that has a tooltip.

• The igxTooltipTarget directive extends the igxToggleAction directive.
• The igxTooltipTarget directive is exported with the name tooltipTarget.

<!--simpleTooltip.component.html-->

<igx-avatar
  class="avatar"
  #target="tooltipTarget"
  igxTooltipTarget
  src="assets/images/avatar/10.jpg"
  size="medium"
  shape="circle">
</igx-avatar>

Dica de ferramenta

Now let's create the tooltip element itself! Since we want a simple text tooltip, we will define an ordinary div element with text inside and set the igxTooltip directive on it, which marks it as a tooltip.

• The igxTooltip directive extends the igxToggle directive.
• The igxTooltip directive is exported with the name tooltip.

<!--simpleTooltip.component.html-->

<div #tooltipRef="tooltip" igxTooltip>Her name is Madelyn James</div>

Attach tooltip to target

Now that we have both our target and tooltip defined, all that's left for us to do is assign the tooltip's reference to the igxTooltipTarget selector of the target.

<!--simpleTooltip.component.html-->

<igx-avatar
  class="avatar"
  #target="tooltipTarget"
  [igxTooltipTarget]="tooltipRef"
  src="assets/images/avatar/10.jpg"
  size="medium"
  shape="circle">
</igx-avatar>

<div #tooltipRef="tooltip" igxTooltip>Her name is Madelyn James</div>

Se tudo correr bem, você deverá ver o exemplo mostrado na seção Demonstração de dica de ferramenta.

Rich tooltip

The igxTooltip content can be more than just simple text. Since the tooltip itself is a regular element in the markup, you can enhance its content by adding any elements you need and styling them accordingly.

Let's expand on the use of the igxTooltip and use it to provide more details for a specific location on a map! We'll use a simple div to represent our map, the IgxAvatar for a logo in our tooltip and the IgxIcon for the location icon on our map. For this purpose, we will get their respective modules.

// app.module.ts

import { IgxTooltipModule, IgxAvatarModule, IgxIconModule } from 'igniteui-angular';
// import { IgxTooltipModule, IgxAvatarModule, IgxIconModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    ...
    imports: [IgxTooltipModule, IgxAvatarModule, IgxIconModule],
})
export class AppModule {}

Também usaremos os seguintes estilos para nossa aplicação:

/* richTooltip.component.css */

.location:hover {
  cursor: pointer;
}

.map {
  overflow: hidden;
  display: flex;
  align-items: center;
  justify-content: center;
  width: 200px;
  height: 252px;
  background-image: url(assets/images/card/media/infragisticsMap.png);
  border: 1px solid #d4d4d4;
}

.locationTooltip {
  width: 310px;
  background-color: var(--igx-grays-700);
  padding: 3px;
  font-size: 13px;
}

.locationTooltipContent {
  display: flex;
  justify-content: center;
  align-items: center;
}

.logo {
  margin-right: 10px;
  min-width: 25px;
  width: 45px;
  height: 45px;
}

Vamos começar criando nosso mapa. Precisamos de um div simples que tenha como plano de fundo uma imagem com um mapa. Além disso, adicionaremos um ícone que indicará a posição da nossa localização! Como queremos fornecer mais detalhes para essa localização, nosso ícone obviamente será o alvo da dica de ferramenta.

<!--richTooltip.component.html-->

<div class="map">
  <igx-icon
    class="location"
    [style.color]="'blue'"
    fontSet="material"
    [igxTooltipTarget]="locationTooltip"
    >location_on</igx-icon>
  ...
</div>

Agora para a dica de ferramenta! Para seu conteúdo, criaremos um contêiner que será preenchido com alguns elementos de informação de texto e um avatar. Então, simplesmente anexaremos a dica de ferramenta ao alvo e incluiremos um estilo CSS bacana!

<!--richTooltip.component.html-->

<div class="wrapper">
  <div class="map">
    <igx-icon
      class="location"
      [style.color]="'blue'"
      fontSet="material"
      [igxTooltipTarget]="locationTooltip"
      >location_on</igx-icon>

    <div class="locationTooltip" #locationTooltip="tooltip" igxTooltip>
      <div class="locationTooltipContent">
        <igx-avatar
          class="logo"
          src="assets/images/card/avatars/igLogo.png"
          size="medium"
          shape="square">
        </igx-avatar>
        <div>
          <div>Infragistics Inc. HQ</div>
          <div>2 Commerce Dr, Cranbury, NJ 08512, USA</div>
        </div>
      </div>
    </div>
  </div>
</div>

Se tudo correr bem, é assim que nossa localização e dica de ferramenta devem ficar:

Advanced Example

The tooltip integrates seamlessly with other components, allowing you to create advanced tooltips that contain components within them. In the following example, you can see how we create descriptive tooltips by using the IgxList, IgxAvatar, IgxIcon, IgxBadge, IgxButton, IgxCard and IgxCategoryChart components.

Show/Hide delay settings

What if we want to control the amount of time that should pass before showing and hiding the tooltip? For this purpose we can use the showDelay and the hideDelay properties of the igxTooltipTarget directive. Both properties are of type number and take time in milliseconds.

Note

The built-in UI interaction behavior of the IgxTooltipTargetDirective works by taking showDelay and hideDelay property values into account. Showing and hiding the tooltip through the API or the API of the IgxTooltipDirective does NOT take the showDelay and hideDelay property values into account. If necessary, such logic would have to be implemented manually according to the application's specifics.

Overlay configuration

Both the igxTooltip and igxTooltipTarget directives use the IgxOverlayService to open and close the respective tooltip element.

The igxTooltipTarget directive exposes a positionSettings property, which can be used to customize the animations of our tooltip, its position in the UI and a lot more! If this property is not set, then default position settings will be used.

To further customize the tooltip, use the overlaySettings property (inherited from the igxToggleAction).

<igx-icon [igxTooltipTarget]="tooltipRef" [positionSettings]="positionSettings" [overlaySettings]="overlaySettings">
  info
</igx-icon>

<div #tooltipRef="tooltip" igxTooltip>Her name is Madelyn James</div>

public positionSettings: PositionSettings = {
  horizontalDirection: HorizontalAlignment.Left,
  horizontalStartPoint: HorizontalAlignment.Left,
  verticalDirection: VerticalAlignment.Top,
  verticalStartPoint: VerticalAlignment.Bottom,
  openAnimation: useAnimation(slideInTop, { params: { duration: '2000ms' } }),
  closeAnimation: useAnimation(slideOutBottom, { params: { duration: '2000ms'} }),
  offset: 10
}

public overlaySettings: OverlaySettings = {
  closeOnEscape: false,
};

Note

Any property that is set through the positionSettings or overlaySettings will override the same property from the default settings and will have a direct impact on the tooltip.

Additional Properties

Apart from the properties we've already covered, the igxTooltipTarget offers a variety of additional properties that allow you to further configure the tooltip's behavior and appearance.

You can make the tooltip "sticky" using the sticky property, which adds a close button and keeps the tooltip visible until the user closes it manually - either by clicking the close button or pressing the Esc key. This behavior overrides the default hover behavior, preventing the tooltip from disappearing when the user stops hovering over the target element.

<igx-icon [igxTooltipTarget]="tooltipRef" [sticky]="true">
  info
</igx-icon>

<div #tooltipRef="tooltip" igxTooltip>Her name is Madelyn James</div>

To customize the default close button, use the closeButtonTemplate property.

<igx-icon [igxTooltipTarget]="tooltipRef" [sticky]="true" [closeButtonTemplate]="customTemplate">
  info
</igx-icon>

<ng-template #customTemplate>
  <igx-icon>cancel</igx-icon>
</ng-template>

<div #tooltipRef="tooltip" igxTooltip>Her name is Madelyn James</div>

Note

Any custom content added via the closeButtonTemplate is rendered only when the tooltip is in sticky mode.

Additionally, you can add an arrow indicator to the tooltip by using the hasArrow property.

<igx-icon [igxTooltipTarget]="tooltipRef" [hasArrow]="true">
  info
</igx-icon>

<div #tooltipRef="tooltip" igxTooltip>Her name is Madelyn James</div>

The arrow element is positioned based on the provided position settings. If the directions and starting points do not correspond to any of the predefined position values, the arrow is positioned in the top middle side of the tooltip (default tooltip position bottom).

Valores de posição predefinidos

Posição	Direção horizontal	Ponto de partida horizontal	Direção vertical	Ponto de partida vertical
principal	AlinhamentoHorizontal.Centro	AlinhamentoHorizontal.Centro	VerticalAlignment.Top	VerticalAlignment.Top
começo de primeira	AlinhamentoHorizontal.Direita	AlinhamentoHorizontal.Esquerda	VerticalAlignment.Top	VerticalAlignment.Top
topo de gama	AlinhamentoHorizontal.Esquerda	AlinhamentoHorizontal.Direita	VerticalAlignment.Top	VerticalAlignment.Top
fundo	AlinhamentoHorizontal.Centro	AlinhamentoHorizontal.Centro	AlinhamentoVertical.Bottom	AlinhamentoVertical.Bottom
começo de baixo	AlinhamentoHorizontal.Direita	AlinhamentoHorizontal.Esquerda	AlinhamentoVertical.Bottom	AlinhamentoVertical.Bottom
extremidade inferior	AlinhamentoHorizontal.Esquerda	AlinhamentoHorizontal.Direita	AlinhamentoVertical.Bottom	AlinhamentoVertical.Bottom
Certo	AlinhamentoHorizontal.Direita	AlinhamentoHorizontal.Direita	AlinhamentoVertical.Meio	AlinhamentoVertical.Meio
início direito	AlinhamentoHorizontal.Direita	AlinhamentoHorizontal.Direita	AlinhamentoVertical.Bottom	VerticalAlignment.Top
extremidade direita	AlinhamentoHorizontal.Direita	AlinhamentoHorizontal.Direita	VerticalAlignment.Top	AlinhamentoVertical.Bottom
Esquerda	AlinhamentoHorizontal.Esquerda	AlinhamentoHorizontal.Esquerda	AlinhamentoVertical.Meio	AlinhamentoVertical.Meio
início esquerdo	AlinhamentoHorizontal.Esquerda	AlinhamentoHorizontal.Esquerda	AlinhamentoVertical.Bottom	VerticalAlignment.Top
extremidade esquerda	AlinhamentoHorizontal.Esquerda	AlinhamentoHorizontal.Esquerda	VerticalAlignment.Top	AlinhamentoVertical.Bottom

No exemplo a seguir, você pode ver uma demonstração de todas as opções de posição e o comportamento de posicionamento da seta em ação:

Personalizando a posição da seta

To customize the arrow's position, you can override the positionArrow(arrow: HTMLElement, arrowFit: ArrowFit) method.

Por exemplo:

export class CustomStrategy extends TooltipPositioningStrategy {
  constructor(settings?: PositionSettings) {
    super(settings);
  }

  public override positionArrow(arrow: HTMLElement, arrowFit: ArrowFit): void {
    Object.assign(arrow.style, {
      left: '-0.25rem',
      transform: 'rotate(-45deg)',
      [arrowFit.direction]: '-0.25rem',
    });
  }
}

public overlaySettings: OverlaySettings = {
  positionStrategy: new CustomStrategy({
    horizontalDirection: HorizontalAlignment.Right,
    horizontalStartPoint: HorizontalAlignment.Right,
    verticalDirection: VerticalAlignment.Bottom,
    verticalStartPoint: VerticalAlignment.Bottom,
  })
};

<igx-icon [igxTooltipTarget]="tooltipRef" [hasArrow]="true" [overlaySettings]="overlaySettings">
  info
</igx-icon>

<div #tooltipRef="tooltip" igxTooltip>Her name is Madelyn James</div>

Estilização

To get started with styling the tooltip, we need to import the index file, where all the theme functions and component mixins live:

@use "igniteui-angular/theming" as *;

// IMPORTANT: Prior to Ignite UI for Angular version 13 use:
// @import '~igniteui-angular/lib/core/styles/themes/index';

Following the simplest approach, we create a new theme that extends the tooltip-theme and provide the $text-color, $background and the $border-radius parameters.

$dark-tooltip: tooltip-theme(
  $text-color: #ecaa53,
  $background: #011627,
  $border-radius: 6px,
);

Note

In order to style any additional components that are used as part of the tooltip's content (such as IgxButton, IgxSwitch, etc.), an additional theme should be created that is specific to the respective component and placed under the tooltip's scope only (so it does not affect the rest of the application).

Since the tooltip uses the IgxOverlayService, in order for our custom theme to reach down the tooltip that we want to style, we will provide a specific outlet where the tooltip will be placed in the DOM when it is visible.

<igx-avatar
  #target="tooltipTarget"
  [igxTooltipTarget]="tooltipRef"
  [igxToggleOutlet]="outlet"
>
</igx-avatar>

<div #outlet="overlay-outlet" igxOverlayOutlet>
  <div #tooltipRef="tooltip" igxTooltip>Her name is Madelyn James</div>
</div>

O último passo é incluir o tema do componente em nosso aplicativo.

@include css-vars($dark-tooltip);

Agora nossa dica de ferramenta estilizada deve ficar assim:

Demo

Styling with Tailwind

Você pode estilizar a dica usando nossas classes utilitárias personalizadas do Tailwind. Certifique-se de configurar o Tailwind primeiro.

Junto com a importação Tailwind na sua folha de estilos global, você pode aplicar os utilitários de tema desejados da seguinte forma:

@import "tailwindcss";
...
@use 'igniteui-theming/tailwind/utilities/material.css';

O arquivo utilitário inclui tantolight as variantes quantodark as do tema.

• Uselight-* as aulas para o tema da luz.
• Usedark-* classes para o tema sombrio.
• Adicione o nome do componente após o prefixo, por exemplo,light-tooltip,dark-tooltip.

Once applied, these classes enable dynamic theme calculations. You can then override the generated CSS variables using arbitrary properties. After the colon, provide any valid CSS color format (HEX, CSS variable, RGB, etc.).

Você pode encontrar a lista completa de propriedades no Tema IgxTooltip. A sintaxe é a seguinte:

<div
  class="!light-tooltip ![--background:#90B69F]"
  #tooltipRef="tooltip"
  igxTooltip>
  Her name is Madelyn James
</div>

Note

O ponto de exclamação(!) é necessário para garantir que a classe utilitária tenha prioridade. O Tailwind aplica estilos em camadas e, sem marcar esses estilos como importantes, eles serão substituídos pelo tema padrão do componente.

No final, sua dica deve ficar assim:

Accessibility

The igxTooltip is built with accessibility in mind and includes the following properties and ARIA attributes:

• id property - autogenerated if not set by the developer.
• role - When the tooltip is in its default behavior, role="tooltip" is applied. If the sticky property is enabled, the role changes to status.
• aria-hidden - automatically updated depending on whether the tooltip is visible or not.

By setting the aria-describedby attribute of the target to its respective tooltip's id, a reference will be provided to the tooltip element. This provides screen readers the information needed to read out the tooltip's contents when the end-user triggers the tooltip.

Cuidado extra deve ser tomado nos seguintes cenários:

• O conteúdo da dica de ferramenta é muito complexo para ser interpretado automaticamente.
• A dica de ferramenta é usada com um comportamento implementado manualmente (por exemplo, mostrar/ocultar manualmente) em vez do comportamento integrado.
• O elemento alvo não pode ser focado.

Notes and Limitations

Limitação	Descrição
Estratégia de posição personalizada com seta	AigxTooltipTarget diretiva usa oTooltipPositionStrategy para posicionar a dica de ferramenta e o elemento de seta. Se um costumepositionStrategy for usado ehasArrow definido comotrue, a estratégia personalizada deverá estender oTooltipPositionStrategy. Caso contrário, a seta não será exibida.

API References

Neste artigo, aprendemos como criar, configurar e estilizar dicas de ferramentas incríveis para os elementos em nossa página! Também usamos alguns componentes adicionais Ignite UI for Angular como ícones e avatares, para melhorar o design do nosso aplicativo! As respectivas APIs estão listadas abaixo:

• IgxTooltipDiretiva
• IgxTooltipTargetDirectiva

Componentes e/ou diretivas adicionais que foram usados:

• Componente IgxAvatar
• Componente IgxIcon
• IgxToggleDirectiva
• IgxToggleActionDirectiva

Styles:

• Estilos de IgxTooltipDirective
• Estilos de componentes IgxAvatar
• Estilos IgxIconComponent

Additional Resources

Nossa comunidade é ativa e sempre acolhedora para novas ideias.

• Ignite UI for Angular Fóruns
• Ignite UI for Angular GitHub