Skip to content

Latest commit

 

History

History
461 lines (314 loc) · 7.98 KB

MIGRATION_GUIDE.md

File metadata and controls

461 lines (314 loc) · 7.98 KB

Migration Guide: v4 to v5

Node

Make sure you have DEV warnings enabled by setting NODE_ENV=development and ensuring your bundler replaces process.env.NODE_ENV with the string "development".

  • webpack: via mode option
  • Rollup: via rollup-plugin-replace
  • Parcel: automatic
  • Browserify/Gulp/Grunt/others: View details

Browser

<script src="https://unpkg.com/popper.js@1"></script>
<!-- Specify development file -->
<script src="https://unpkg.com/tippy.js@5/dist/tippy-bundle.iife.js"></script>
<!-- 
When you're finished, you can remove everything after @5 
(or when deploying for production) 
<script src="https://unpkg.com/tippy.js@5"></script>
-->

Imports

Previously, the default import injected the CSS stylesheet into <head>:

import tippy from 'tippy.js';

In v5, this import is now side-effect free to work better with dependencies when users have CSP enabled or using frameworks that control the <head>.

You should import the CSS separately:

import tippy from 'tippy.js';
import 'tippy.js/dist/tippy.css';

You can however opt-in to use the injected CSS version, just like v4:

// Just like v4
import tippy from 'tippy.js/dist/tippy-bundle.esm';

// Or CommonJS:
const tippy = require('tippy.js/dist/tippy-bundle.cjs');

data-tippy attribute

This technique of auto initialization was removed to keep the import side-effect free. Initializing via the tippy() constructor is required.

Animations

If you want the animateFill effect back (it's no longer default)

View details

Node:

import tippy, {animateFill} from 'tippy.js';
import 'tippy.js/dist/tippy.css';

// These stylesheets are required for it to work
import 'tippy.js/dist/backdrop.css';
import 'tippy.js/animations/shift-away.css';

tippy(targets, {
  animateFill: true,
  plugins: [animateFill],
});

Browser:

<link rel="stylesheet" href="https://unpkg.com/tippy.js@5/dist/backdrop.css" />
<link
  rel="stylesheet"
  href="https://unpkg.com/tippy.js@5/animations/shift-away.css"
/>
<script src="https://unpkg.com/popper.js@1"></script>
<script src="https://unpkg.com/tippy.js@5"></script>
<script>
  tippy(targets, {
    content: 'tooltip',
    animateFill: true,
  });
</script>

If you were using default animations or creating custom animations

View details
  • Make sure your visible state has no translation (of 0px, instead of 10px like before).
  • shift-away, shift-toward, scale and perspective need to be imported separately now.

Node:

import 'tippy.js/animations/scale.css';

Browser:

<link
  rel="stylesheet"
  href="https://unpkg.com/tippy.js@5/animations/scale.css"
/>

Props

If you were using interactive: true

View details

When using interactive: true, the tippy may be invisible or appear cut off if your reference element is in a container with:

  • position (e.g. fixed, absolute, sticky)
  • overflow: hidden

To fix add the following prop (recommended):

tippy(reference, {
  // ...
  popperOptions: {
    positionFixed: true,
  },
});

Or, if the above causes issues:

tippy(reference, {
  // ...
  appendTo: document.body,
});

⚠️ For the latter, you need to be employing focus mangement for accessibility.

If you were using arrowType: 'round'

View details

Import the svg-arrow CSS, and the roundArrow string, and use the arrow prop instead.

Node:

import {roundArrow} from 'tippy.js';
import 'tippy.js/dist/svg-arrow.css';

tippy(targets, {
  arrow: roundArrow,
});

Browser:

<link rel="stylesheet" href="https://unpkg.com/tippy.js@5/dist/svg-arrow.css" />
<script>
  tippy(targets, {
    arrow: tippy.roundArrow,
  });
</script>

If you were using followCursor

View details

Node:

import tippy, {followCursor} from 'tippy.js';

tippy('button', {
  followCursor: true,
  plugins: [followCursor],
});

Browser:

(Works as before.)

If you were using sticky

View details

Node:

import tippy, {sticky} from 'tippy.js';

tippy('button', {
  sticky: true,
  plugins: [sticky],
});

Browser:

(Works as before.)

If you were using target

View details

Use delegate().

Node:

import tippy, {delegate} from 'tippy.js';

delegate('#parent', {target: 'button'});

Browser:

<script src="https://unpkg.com/popper.js@1"></script>
<script src="https://unpkg.com/tippy.js@5"></script>
<script>
  tippy.delegate('#parent', {target: 'button'});
</script>

If you were using showOnInit

View details

It's now named showOnCreate, to match the onCreate lifecycle hook

If you were using size

View details

It's been removed, as it's more flexible to just use a theme and specify the font-size and padding properties.

If you were using touchHold

View details

Use touch: "hold" instead.

If you were using a11y

View details

Ensure non-focusable elements have tabindex="0" added to them. Otherwise, use natively focusable elements everywhere possible.

If you were using wait

View details

Use the onTrigger and onUntrigger lifecycles and temporarily disable the instance.

tippy(targets, {
  onTrigger(instance) {
    instance.disable();
    // Make your async call...
    // Once finished:
    instance.enable();
    instance.show();
  },
  onUntrigger(instance) {
    // Re-enable the instance here depending on the async cancellation logic
    instance.enable();
  },
});

Instances

If you were using instance.set()

View details 
- instance.set({});
+ instance.setProps({});

Static methods

If you were using tippy.setDefaults()

View details 
- tippy.defaults;
+ tippy.defaultProps;
- tippy.setDefaults({});
+ tippy.setDefaultProps({});

If you were using tippy.hideAll()

View details

In ESM/CJS contexts, it's no longer attached to tippy

Node:

import {hideAll} from 'tippy.js';

hideAll();

Browser:

(Works as before.)

If you were using tippy.group()

View details

Use createSingleton().

Node:

import tippy, {createSingleton} from 'tippy.js';

createSingleton(tippy('button'), {delay: 1000});

Browser:

<script src="https://unpkg.com/popper.js@1"></script>
<script src="https://unpkg.com/tippy.js@5"></script>
<script>
  tippy.createSingleton(tippy('button'), {delay: 1000});
</script>

Themes

If you were using the included themes

View details
  • google is now material

If you were creating custom themes

View details
  • [x-placement] attribute is now [data-placement]
  • [x-out-of-boundaries] is now [data-out-of-boundaries]
  • .tippy-roundarrow is now .tippy-svg-arrow
  • .tippy-tooltip no longer has padding on it, rather the .tippy-content selector does.
  • .tippy-tooltip no longer has text-align: center

Other

If you were using virtual reference objects

View details

Set instance.popperInstance.reference = ReferenceObject in the onTrigger lifecycle, or onCreate with lazy: false.

Types

View details
  • Props is not Partial anymore, it's Required
  • Options removed (use Partial<Props>)
  • BasicPlacement renamed to BasePlacement