Tippy.js 3: alpha 0

The first alpha release of Tippy.js v3.

npm i tippy.js@next

What's changed?

You no longer use a title attribute on elements, and the html option has been removed. Both functionalities have been streamlined into a single prop: content.

Method 1: Auto

<button data-tippy="Tooltip">Text</button>
<button data-tippy="<strong>HTML</strong>">Text</button>

Elements with a data-tippy attribute are automatically given a tooltip. You no longer need to touch JavaScript. (Note on performance: It takes <0.5ms to do this check on a page if there are no tooltips).

Method 2: content

You can give elements a data-tippy-content attribute and use the function:

<button data-tippy-content="Tooltip">Text</button>
<script>tippy('button')</script>

Or specify the content as an option.

<button>Text</button>
<script>tippy('button', { content: 'Tooltip' })</script>

It can contain HTML, and you can use an HTMLElement as the value.

tippy() call

The object that is returned:

• selector is now named targets
• tooltips is now named instances

Instances

• New popperChildren property: access the children of the popper element easily without needing to do query selections or manual DOM walking.
• options has been renamed to props. Options are the props you supply optionally to tippy(), but it doesn't make sense for the tooltip configuration object to be called options. Instead, it's now props, inspired by React.
• state object properties are all prefixed with is because they are boolean values.
• listeners made private

Methods

The most useful new method is set(). It allows you to update the props of a tooltip after it has been created.

const tip = tippy.one('.btn', { 
  content: 'Hello!', 
  arrow: true,
  delay: 500
})

// Later on...
tip.set({ 
  content: 'Bye!', 
  arrow: false,
  delay: 0
})

Static

• tippy.setDefaults(props) - pass an object in to change the default configuration
• tippy.browser removed

Options/Props

• a11y: true - (accessibility shorthand): ensure the reference element can receive focus
• allowTitleHTML: true is now allowHTML
• hideOnClick changes "persistent" to "toggle" and it has the opposite behavior. This means that hideOnClick: false will prevent click-triggered tooltips from ever hiding unless you specify "toggle". Not 100% sure on this, however.
• touch: true- display the tooltip on touch devices?
• createPopperInstanceOnInit: false is now lazy: true. More concise name.
• showOnInit: false - show the tooltip immediately?
• maxWidth removed. Should be handled by a theme in CSS because of narrow mobile devices.
• multiple: false - can the reference have multiple tippys? Currently each new instance overrides the previous _tippy property. It most likely needs to be turned into an array on the second init, but I fear this causes unpredictable behavior. (The previous option which allowed multiple click triggered tooltips to be open is now gone. I don't see much demand for it, but it might return as a different name).
• duration/delay: you can now leave a value undefined in the array and the default value is used. e.g. duration: [, 100] (use default for show) or duration: [100] (use default for hide). It's more concise than an object: duration: { hide: 100 } but the syntax is kind of messy. Might change this.

Accessibility/focus handling

Focus handling and accessibility has been improved. Tabbing/keyboard nav around interactive tooltips now works better.

Handling fallback for unsupported browsers

I believe this should be handled by the user, not the library.

The best way is to inline the tooltip content next to the reference element on old mobile & desktop browsers for interactive HTML popovers. For simple tooltips on desktop, manually set the title property on the element.

Unsupported = <0.5% worldwide usage or nonstandard browsers.

TODO before final release

• Fix #193
• More configurable animations. Currently can be handled with theme but requires lots of boilerplate selectors. Would be nice to make it declarative as an option.
• #174: Cooler animations someday?
• Finish writing tests. There's over 200, but I probably need to move back to a browser from Jest because there are too many things that need to be tested in a real browser using a layout engine.
• Package: sourcemaps, ES module (maybe, since there's not much to treeshake)