Tippy.js 一个轻量级的,纯JS库工具提示(tooltip)库
Tippy.js 一个轻量级的,纯JS库工具提示(tooltip)库
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 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.
-
✅ roleoption - instead oftooltip, certain popovers may need to bemenuordialogfor accessibility reasons.
tippy('button', {
role: 'menu'
})
Assets
2
Features
Fixes
popper.js^1.14.6includes position rounding fixes- Fix slight text blurriness on Safari when
animateFill: true googletheme adheres tosizeoption- Arrow centering fixes for
light-border.cssdue to Popper.js issue
Assets
2
Deprecations
- Deprecate
tippy.useCapture()and make capture phase for the global click listener default. This prevents the need to wrap calls to.show()insetTimeoutif manually triggering the tooltip after a click event somewhere
Fixes
- Add
characterDatato the popper mutation observer so changes to textual content within a tippy is detected and its position updated accordingly. Mainly noticeable in React updates. - Use
state.isMountedoverstate.isVisibleto determine ifhide(0)should be called when destroying a tippy. This was not a leak but caused glitches when using the React component after changing routes and unmounting the Tippy component.
Assets
2
v3.0.0-alpha.1
- Include IE11 transitionend fix
- Subtler animations for
scaleandperspective - Popper.js 1.14.4
- Include
esmdirectory andmodulefield in package.json
v3.0.0-alpha.0
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:
selectoris now namedtargetstooltipsis now namedinstances
Instances
- New
popperChildrenproperty: access the children of the popper element easily without needing to do query selections or manual DOM walking. optionshas been renamed toprops. Options are the props you supply optionally totippy(), but it doesn't make sense for the tooltip configuration object to be calledoptions. Instead, it's nowprops, inspired by React.stateobject properties are all prefixed withisbecause they are boolean values.listenersmade 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 configurationtippy.browserremoved
Options/Props
a11y: true- (accessibility shorthand): ensure the reference element can receive focusallowTitleHTML: trueis nowallowHTMLhideOnClickchanges"persistent"to"toggle"and it has the opposite behavior. This means thathideOnClick: falsewill preventclick-triggered tooltips from ever hiding unless you specify"toggle". Not 100% sure on this, however.touch: true- display the tooltip on touch devices?createPopperInstanceOnInit: falseis nowlazy: true. More concise name.showOnInit: false- show the tooltip immediately?maxWidthremoved. 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_tippyproperty. 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) orduration: [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
themebut 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)
- fix: #249
- fix: remove problematic iOS code that autoclicks which sometimes causes doubles clicks
- Upgrade Popper.js dependency:
1.14.1=>1.14.2which has some nice fixes for positioning and bundle size😄 - Add new static method:
tippy.one()for creating one single tooltip, it will return the tooltip instance directly - css: remove
pointer-eventson round arrow SVG if not interactive
- Upgrade Popper.js dependency:
1.13.0=>1.14.1 - Adds
tippy.versionproperty to the module, and injects a banner at the top of unminified files - Better handling of focus/tabbing & interactivity
- fix #207
- fix #185: set
.tippy-popperline-height to1.4to prevent descender letters like "g" and "y" from being cut off depending on the font/browser/OS. Will not affect themes with custom line-heights because of lower specificity.
refresh deps
| Watchers：68 |
| Star：5468 |
| Fork：320 |
| 创建时间： 2017-04-01 14:51:35 |
| 最后Commits： 昨天 |
| 许可协议：MIT |
| 分类：提示控件Tips / JavaScript开发 |
| 收录时间：2017-04-06 08:20:40 |
bfbf260Fixes
animateFillbeing broken, andonShown/onHiddennot being called (#427)<head>when injecting CSS