Migrating Popups from Semantic UI

In this document we'll be using SUI for ng2-semantic-ui and Bootstrap for ng-bootstrap. We'll also be using <span> elements in the examples, but any element can be associated with a tooltip.

See the SUI popup specs for more info.

Migrating simple popups

"Simple" SUI popups show fixed text. They follow this structure:

<span suiPopup popupText="..."> ... </span>

The UI Guidelines provide a CSS-only partial re-implementation of those popups. For more complex use cases (e.g., dynamically generated tooltip text; using a template for the tooltip body), see below.

<span tooltip-text="..."> ... </span>

Attributes tooltip-position and tooltip-size can also be used to customize the popup.

Notes

• The default value for tooltip-position is top center. Valid values are

  • top left top center top right
  • bottom left bottom center bottom right
  • left
  • right

• The default value for tooltip-size is md. Valid values are

  • sm
  • md
  • lg
  • xl
  • xxl

• Tooltip text can be broken down in multiple lines. When rendering, line breaks are preserved but whitespace is compressed.

  <button class="btn btn-primary" (click)="..."
        tooltip-text="First line.
                      Second line.
                      Third and last line."
   ...
  </button>

Migrating dynamic popups

"Dynamic" SUI popups show text that's computed at runtime and accessed via Angular interpolation. They follow this structure:

<span suiPopup popupText="{{ ... }}"> ... </span>

The equivalent Boostrap component is based on ngbPopover. (See the specs for more info.)

<span ngbPopover="{{ ... }}"
      triggers="mouseenter:mouseleave"
      container="body">
    ... 
</span>

Notes

• Attribute container="body" (see here) is mandatory when the ngbPopover is used on a <tr> or <td> element; with other elements it can be omitted.

Migrating template-based popups

SUI template-based popups follow this structure:

<ng-template let-popup #popupTemplate>
    ...
</ng-template>

<span suiPopup [popupTemplate]="popupTemplate"> ... </span>

Notes

• The optional let-popup notation allows you to access the popup in the body of a SUI template, for instance:

  <button (click)="popup.close()"> Close </button>

• There is no let-popup equivalent notation for Bootstrap.

The equivalent Boostrap component is also based on ngbPopover. (See the template-specific specs for more info.)

<ng-template #popupTemplate>
    ...
</ng-template>

<span [ngbPopover]="popupTemplate"
      triggers="mouseenter:mouseleave"
      container="body">
    ... 
</span>

Notes

• Attribute container="body" (see here) is mandatory when the ngbPopover is used on a <tr> or <td> element; with other elements it can be omitted.

ngbTooltip

Bootstrap tooltips can be implemented as ngbTooltip-based components as well. They have a very similar structure to SUI popups but are rather inflexible. A solution based on ngbPopover allows better styling and finer control, and it should be preferred over ngbTooltip, even though the syntax is more verbose.

However, ngbTooltip-based tooltips may be of value in a migration as well. A template-based example would be:

<ng-template #popupTemplate>
    ...
</ng-template>

<span [ngbTooltip]="popupTemplate"> ... </span>

Notes

• A tooltip placed on a <td> element can interfere with table layout. If that happens, a possible ugly but effective workaround is to wrap that element in a <span> or <div> element.

  <div>
    <td [ngbTooltip]="popupTemplate"> ... </td>
  </div>