Tippy.js 一个轻量级的,纯JS库工具提示(tooltip)库
Tippy.js 一个轻量级的,纯JS库工具提示(tooltip)库
Fixes
- Fix
followCursorhaving incorrect offset when using a variation placement (-startor-end) (#513)
Assets
2
Fixes
- Mounting behavior (IE11 scrollbar flicker) (#509)
followCursorfixes (respects boundary & fix regression where initial was not placed correctly on touch devices on first show)- Ensure
destroy()'s unmounting of the tippy can never be impeded - Fix the longstanding interactive scrolling issue
- Fix path selector having
pointer-events: auto(#504)
Assets
2
Fixes
Assets
2
Features
- Added
triggerTargetoption to apply the trigger listeners to a different node from the positioning reference - Added
onTriggeroption to allow calls to.set()to change the reference position and instance props based on the event before the tooltip is shown without interrupting the lifecycle (unlikewait) - Added ability to pass a ReferenceElement to HideAllOptions.exclude for references with multiple tippys
Fixes
- Make
tippy.group()andupdateDurationupdateable - Fix when
popperOptions.onCreateandpopperOptions.onUpdateare called so they match the actual invocations by Popper.js - Fix
followCursornot respectingpopperOptions.modifiers.preventOverflow.padding - Fix multiple tippys from only displaying one if using touch and
hideOnClick: true - Fix the tooltip moving with the cursor if over the popper element when using
followCursor: '{horizontal, vertical}'andinteractive: true - [TypeScript] Fix instance.reference type to account for VirtualReference
Assets
2
Features
- Add
x-placementattribute to tooltip node, allowing you to style without needing to use the.tippy-popperselector
Example
Before:
.tippy-popper[x-placement^='top'] .tippy-tooltip.my-theme .tippy-arrow {
border-top-color: pink;
}
After:
.tippy-tooltip.my-theme[x-placement^='top'] .tippy-arrow {
border-top-color: pink;
}
Fixes
- Apply correct mutations when calling
.set()with apopperInstancedependency update
Assets
2
This release mainly fixes some minor CSS issues
Fixes
- Make
remunits align with whole pixels using 16px base default - Size round arrow closer to default sharp arrow so it reaches the edges of the popper + reduce arrow margins overall
- Fix infinite loop when
popperOptionsisundefinedinstead of an object - Fix small gaps when using the round arrow in Edge/IE11
- Fix longstanding issue (since v0) of Popper's
preventOverflownot taking into account thedistanceprop
Assets
2
Fixes
Assets
2
Assets
2
Install
npm i tippy.js@latest
Overall minzipped size has been reduced by about 400 bytes
Features / Improvements
-
✅ followCursor: 'initial'works on touch devices too
-
✅ Padding between popper and container/viewport edges has been reduced to 3px from 5px by default
-
✅ scaleanimation has its transform origin sticking to the reference element
-
✅ tippy.hideAll()method is now actually useful!
It no longer checks hideOnClick unexpectedly. In other words:
tippy.hideAll()
Does exactly what it says. All tippys will be hidden no matter what (using their own specified durations).
There's even options now too, for example, make all of them hide instantly (useful for scrolling):
tippy.hideAll({ duration: 0 })
Or exclude a particular instance from hiding:
tippy.hideAll({ exclude: tippyInstance })
-
✅ tippy.group()method - finally, a built-in solution to #81!
How to use it:
const instances = tippy('button', { delay: 1000 })
tippy.group(instances)
// Optional:
tippy.group(instances, {
duration: number | [number, number], // instead of 0 between each show,
delay: number | [number, number], // if you didn't specify a delay in the instances
})
As simple as that, the tooltips will now instantly show when hovering between items in the group instead of waiting for the delay sluggishly.
-
✅ updateDurationoption is now0instead of200by default
Flips don't have the weird transition if using flipOnUpdate: true (note that it's off by default now). Specifying a number now uses true smooth flips, where the popper element smoothly transitions from one placement to another. The effect is quite satisfying.
-
✅ roleoption - instead oftooltip, certain popovers may need to bemenuordialogfor accessibility reasons.
tippy('button', {
role: 'menu'
})
Breaking changes
-
🔴 You no longer need to import CSS when using modules. It gets injected to the very top of the<head>, like the UMD version.
// v3
import tippy from 'tippy.js'
import 'tippy.js/dist/tippy.css'
// v4
import tippy from 'tippy.js'
Also, files renamed to index instead of tippy.
In case you don't want this, you still can import it separately:
import tippy from 'tippy.js/esm'
import 'tippy.js/index.css'
Additionally, everything exists in the root directory instead of under dist/. For example, themes:
import 'tippy.js/themes/light.css'
Why: cleaner import experience for consumers
-
🔴 popper.jsis external in all formats, so no moretippy.standalone. This means CDN includes must reference it separately.
<script src="https://unpkg.com/popper.js@1/dist/umd/popper.min.js"></script>
<script src="https://unpkg.com/tippy.js@4"></script>
<script>
tippy('button')
</script>
Why: to prevent popper.js from becoming outdated and lagging behind popper releases, works like a dependency should
-
🔴 Removetippy.one(). Instead, an instance will be returned in two cases: if the reference is either an element or a virtual element
// v3
const collection = tippy('.btn')
const collection = tippy(document.querySelector('.btn'))
const instance = tippy.one('.btn')
const instance = tippy.one(document.querySelectorAll('.btn'))
// v4
// Instance
const instance = tippy(document.querySelector('.btn'))
const instance = tippy(virtualElement)
// Instance[]
const instances = tippy('#btn')
const instances = tippy('.btn')
const instances = tippy(document.querySelectorAll('.btn'))
Why: collections are not useful and don't need to exist. But we want to avoid an opaque return value if using a certain type. Therefore even if only a single element is given an instance when using a CSS selector, it always returns an array.
-
🔴 Removetippy.useCapture()andtippy.disableAnimations()
Why: .useCapture() is now default in v3 anyway. .disableAnimations() was for testing environments however the new delay value causes async behavior when hiding. In testing environments, use the following call to make everything synchronous:
tippy.setDefaults({ duration: 0, delay: 0 })
-
🔴 RemovearrowTransformoption
Why: Since introducing a bordered theme (light-border), using transforms distorts the shape of the arrow border. Arrow transforms should be specified in CSS using a theme.
-
🔴 RemoveautoFocusandshouldPopperHideOnBluroptions. Remove all focus handling and leave it up to the developer.
Why: The recommended accessible popover is to append it directly after the reference element which requires no focus handling. This will ensure focusable elements inside the tippy can be tabbed to afterwards. Sometimes this can be problematic though, with regards to z-index /stacking issues and the popover needs to be appended to the body. In this case it's up to the developer to create modal-like behavior with a close button and focus trapping, they can programmatically call .focus() where need be.
-
🔴 The AJAX image example (smooth transition): you must explicitly define transition styles on the tooltip now.
e.g. in the onShow() lifecycle:
onShow(instance) {
const { tooltip } = instance.popperChildren
tooltip.style.transitionDuration = '0.2s'
tooltip.style.transitionProperty = 'visibility, opacity, height'
}
-
⚠️ RenameperformancetoignoreAttributes
Why: ignoreAttributes describes what it's doing, performance described the side effect of doing it
-
⚠️ Renametippy.hideAllPoppers()totippy.hideAll()
Why: Shorter and more concise and conveys the same meaning
-
⚠️ In event delegation mode,contentandappendToas functions receive the target element rather than the delegate reference
Why: It's actually useful this way
-
⚠️ RenamelivePlacementtoflipOnUpdate, with much better behavior. It's nowfalseby default. The tippy will still update its position on scroll, but flipping while scrolling/resizing, etc is disabled by default.
Why: Better UX (subjective) to keep the placement static after showing and prevent flips while scrolling
-
⚠️ If yourcontentis an element, and you change elements inside it, you must callinstance.popperInstance.scheduleUpdate().
Why: MutationObserver is not as robust as a ResizeObserver and has been removed. If you want complete accuracy consider using a polyfill for ResizeObserver.
-
⚠️ Opinioned CSS like font-smoothing has been removed. Tippy elements should inherit the global styles as much as possible.
Why: Let the developer have more control and not introduce unexpected styling
Fixes
-
Fix for tippys with delays when leaving the popper, it sometimes would not close
-
Correctly parse
nullin attributes
Assets
2
Install
npm i tippy.js@next
Overall minzipped size has been reduced by about 400 bytes
Breaking changes
-
🔴 You no longer need to import CSS when using modules. It gets injected to the very top of the<head>, like the UMD version.
// v3
import tippy from 'tippy.js'
import 'tippy.js/dist/tippy.css'
// v4
import tippy from 'tippy.js'
Also, files renamed to index instead of tippy.
In case you don't want this, you still can import it separately:
import tippy from 'tippy.js/esm'
import 'tippy.js/index.css'
Additionally, everything exists in the root directory instead of under dist/. For example, themes:
import 'tippy.js/themes/light.css'
Why: cleaner import experience for consumers
-
🔴 popper.jsis external in all formats, so no moretippy.standalone. This means CDN includes must reference it separately.
<script src="https://unpkg.com/popper.js@1/dist/umd/popper.min.js"></script>
<script src="https://unpkg.com/tippy.js@4"></script>
<script>
tippy('button')
</script>
Why: to prevent popper.js from becoming outdated and lagging behind popper releases, works like a dependency should
-
🔴 Removetippy.one(). Instead, an instance will be returned in two cases: if the reference is either an element or a virtual element
// v3
const collection = tippy('.btn')
const collection = tippy(document.querySelector('.btn'))
const instance = tippy.one('.btn')
const instance = tippy.one(document.querySelectorAll('.btn'))
// v4
// Instance
const instance = tippy(document.querySelector('.btn'))
const instance = tippy(virtualElement)
// Instance[]
const instances = tippy('#btn')
const instances = tippy('.btn')
const instances = tippy(document.querySelectorAll('.btn'))
Why: collections are not useful and don't need to exist. But we want to avoid an opaque return value if using a certain type. Therefore even if only a single element is given an instance when using a CSS selector, it always returns an array.
-
🔴 Removetippy.useCapture()andtippy.disableAnimations()
Why: .useCapture() is now default in v3 anyway. .disableAnimations() was for testing environments however the new delay value causes async behavior when hiding. In testing environments, use the following call to make everything synchronous:
tippy.setDefaults({ duration: 0, delay: 0 })
-
🔴 RemovearrowTransformoption
Why: Since introducing a bordered theme (light-border), using transforms distorts the shape of the arrow border. Arrow transforms should be specified in CSS using a theme.
-
🔴 RemoveautoFocusandshouldPopperHideOnBluroptions. Remove all focus handling and leave it up to the developer.
Why: The recommended accessible popover is to append it directly after the reference element which requires no focus handling. This will ensure focusable elements inside the tippy can be tabbed to afterwards. Sometimes this can be problematic though, with regards to z-index /stacking issues and the popover needs to be appended to the body. In this case it's up to the developer to create modal-like behavior with a close button and focus trapping, they can programmatically call .focus() where need be.
-
⚠️ RenameperformancetoignoreAttributes
Why: ignoreAttributes describes what it's doing, performance described the side effect of doing it
-
⚠️ Renametippy.hideAllPoppers()totippy.hideAll()
Why: Shorter and more concise and conveys the same meaning
-
⚠️ In event delegation mode,contentandappendToas functions receive the target element rather than the delegate reference
Why: It's actually useful this way
-
⚠️ RenamelivePlacementtoflipScroll, with much better behavior. It's nowfalseby default. The tippy will still update its position on scroll, but flipping while scrolling is disabled.
Why: Better UX (subjective) to keep the placement static after showing and prevent flips while scrolling
-
⚠️ If yourcontentis an element, and you change elements inside it, you must callinstance.popperInstance.scheduleUpdate().
Why: MutationObserver is not as robust as a ResizeObserver and has been removed. If you want complete accuracy consider using a polyfill for ResizeObserver.
-
⚠️ Opinioned CSS like font-smoothing has been removed. Tippy elements should inherit the global styles as much as possible.
Why: Let the developer have more control and not introduce unexpected styling
Features / Improvements
-
✅ followCursor: 'initial'works on touch devices too
-
✅ updateDurationoption is now0instead of200by default
Flips don't have the weird transition if using flipScroll: true (note that it's off by default now). Specifying a number now uses true smooth flips, where the popper element smoothly transitions from one placement to another. The effect is quite satisfying.
-
✅ Padding between popper and container/viewport edges has been reduced to 2px from 5px by default
-
✅ scaleanimation has its transform origin sticking to the reference element
-
✅ tippy.hideAll()method is now actually useful!
It no longer checks hideOnClick unexpectedly. In other words:
tippy.hideAll()
Does exactly what it says. All tippys will be hidden no matter what (using their own specified durations).
There's even options now
623e841Fixes
stickyoption by preventing repaints on every animation framestylenode before the firststyleorlinktag instead of first childdelayreferenceNodeproperty for followCursor (NOTE: awaiting popper.js@1.16.0 release)