Render tooltips and popovers on components and other HTML elements using HTMLBars.
ember install ember-tooltips
Documentation for usage is below:
Version 1.0.0 removed darsain/tooltip as a dependency, in favor of using custom Ember code.
You can use and see the pre-1.0 version on this branch. Alternatively, install "ember-tooltips": "0.7.0" in your package.json.
Version 2.4.0 introduces lazy rendering. Tooltips and popovers generally don't need to be rendered until the user has interacted with the $target element. Adding enableLazyRendering=true to your component will enable this feature. In version 3.0.0 enableLazyRendering will default to true and you'll be able to opt-out of lazy rendering as necessary.
The easiest way to add a tooltip to any component is with the {{tooltip-on-component}} component:
Or in block form:
Options can be set on the {{tooltip-on-component}} as attributes:
Documentation for supported options is located here.
If you want to add a tooltip to an element that is not an Ember component, you can do so with {{tooltip-on-element}}.
By default, the tooltip will attach itself to its parent element:
Or in block form:
You can also specify the ID of the element to attach the tooltip to:
The target property must be an ID, including the #.
Popovers can be created with {{popover-on-element}} and {{popover-on-component}} with the same target behavior as tooltips.
The same options passed to tooltip components can be passed to popover components. In addition, a hideDelay option is made available for popovers only.
Popovers also benefit from a hide API made publically acessible:
{{#popover-on-element as |popover|}}
Click <a href {{action popover.hide}}>here</a> to hide the popover
{{/popover-on-element}}
Options are set as attributes on the tooltip/popover components. Current tooltip/popover properties this addon supports are:
- class
- delay
- delayOnChange
- duration
- effect
- event
- hideOn
- keepInWindow
- side
- showOn
- spacing
- isShown
- hideDelay (popover only)
- enableLazyRendering
| Type | String |
|---|---|
| Default | none |
Adds a class to any tooltip:
| Type | Number |
|---|---|
| Default | 0 |
Delays showing the tooltip by the given number of milliseconds.
This does not affect the hiding of the tooltip. See also, delayOnChange.
| Type | Boolean |
|---|---|
| Default | true |
Whether or not to enforce the delay even when the user transitions their cursor between multiple target elements with tooltips.
See this animation for a visual explanation:
| Type | Number |
|---|---|
| Default | 0 |
Sets the duration for which the tooltip will be open, in milliseconds. When the tooltip has been opened for the duration set it will hide itself.
The user will still hide the tooltip if the hide event occurs before the duration expires.
| Type | String |
|---|---|
| Default | 'slide' |
Sets the animation used to show and hide the tooltip. Possible options are:
'fade''slide''none'
| Type | String |
|---|---|
| Default | 'hover' |
The event that the tooltip will hide and show for. Possible options are:
'hover''click''focus'(hides on blur)'none'
This event is overwritten by the individual hideOn and showOn properties. In effect, setting event sets hideOn and shownOn for you.
The tooltip can also be shown programatically by passing in the isShown property, documented here.
| Type | String |
|---|---|
| Default | 'none' |
Sets the event that the tooltip will hide on. This overwrites any event set with the event option.
This can be any javascript-emitted event.
This does not affect the event the tooltip shows on. That is set by the showOn option. This will override the event property.
| Type | Boolean |
|---|---|
| Default | true |
Whether to automatically try keep the tooltip in the window. This will override any side you set if the tooltip is rendered partically outside the window.
For example, a target element in the top-left of the screen with a tooltip's side set to left will probably render the tooltip on the right of the target element.
| Type | String |
|---|---|
| Default | 'top' |
Sets the side the tooltip will render on. If keepInWindow is set to true, side can be overwritten to keep the tooltip on screen.
Possible options are:
'top''right''bottom''left'
| Type | String |
|---|---|
| Default | 'none' |
Sets the event that the tooltip will show on. This overwrites any event set with the event option.
This can be any javascript-emitted event.
This does not affect the event the tooltip hides on. That is set by the hideOn option. This will override the event property.
| Type | Number |
|---|---|
| Default | 10 |
Sets the number of pixels the tooltip will render from the target element. A higher number will move the tooltip further from the target. This can be any number.
| Type | Boolean |
|---|---|
| Default | false |
Gives you a programatic way to hide and show a tooltip. Set this value to true to manually show the tooltip.
This can be useful alongside event='none' when you only want to toolip to show when you specific and not based on an user action.
| Type | Number |
|---|---|
| Default | 250 |
POPOVER ONLY: The number of milliseconds before the popover will hide after the user hovers away from the popover and the popover target. This is only applicable when event='hover'.
| Type | Boolean |
|---|---|
| Default | false (will be true in 3.0.0) |
If enabled tooltips and popovers will only be rendered when a user has interacted with the $target element or when isShown=true. This delay in render time is especially useful when many tooltips exist in a page.
You can set the default for any option by extending the {{tooltip-on-element}} component:
{{!--your-app/components/tooltip-on-element}}--}}
import TooltipOnElementComponent from 'ember-tooltips/components/tooltip-on-element';
export default TooltipOnElementComponent.extend({
effect: 'fade',
side: 'bottom',
enableLazyRendering: true,
});Four actions are available for you to hook onto through the tooltip/popover lifecycle:
This addon exposes testing helpers which can be used inside of the consuming app's acceptance and integration tests. We use a tooltip-centric naming convention but these can also be used to test popovers.
assertTooltipVisible(assert): asserts if the tooltip is visible. It checks two attributes on the $tooltip: aria-hidden and data-tether-enabled.assertTooltipNotVisible(assert): asserts if the tooltip is not visible. It checks two attributes on the $tooltip: aria-hidden and data-tether-enabled.assertTooltipRendered(assert): asserts if the tooltip has been rendered. When enableLazyRendering is true the tooltip will only be rendered after the user has interacted with the $target element. A tooltip can be rendered but not visible.assertTooltipNotRendered(assert): asserts if the tooltip has not been rendered. When enableLazyRendering is true the tooltip will only be rendered after the user has interacted with the $target element.assertTooltipSide(assert, { side: 'right' }): asserts that the tooltip is shown on the correct side of the target. Additional options that can be passed areselectorandtargetSelector`.assertTooltipSpacing(assert, { side: 'right', spacing: 10 }): asserts that the tooltip is a given distance from the target (on a given side).sideandspacingmust be passed. Additional options that can be passed areselectorandtargetSelector`.- `assertTooltipContent(assert, { contentString: 'hello' }): asserts that the content of the tooltip matches a given string.
triggerTooltipTargetEvent($targetElement, eventName): triggers an event on the passed element. The event will be triggered within an Ember.run so that the tooltip's asynchronicity is accounted for. eventName can be mouseenter, mouseleave, click, focus, focusin, and blur.
Each test helper also accepts an options object as a final parameter. If a selector property is provided the assertions and actions will be run against the single element found from that selector.
import { assertTooltipVisible, assertTooltipNotVisible, assertTooltipRendered, assertTooltipNotRendered, triggerTooltipTargetEvent } from '../../helpers/ember-tooltips';
...
this.render(hbs`{{tooltip-on-element text='some text' enableLazyRendering=true}}`);
const $tooltipTarget = this.$();
assertTooltipNotRendered(assert);
triggerTooltipTargetEvent($tooltipTarget, 'mouseenter');
assertTooltipRendered(assert);
assertTooltipVisible(assert);
triggerTooltipTargetEvent($tooltipTarget, 'mouseleave');
assertTooltipNotVisible(assert);
...
this.render(hbs`
<div class="tooltip-one-target">
{{tooltip-on-element enableLazyRendering=true class='tooltip-one'}}
</div>
<div class="tooltip-two-target">
{{tooltip-on-element enableLazyRendering=true class='tooltip-two'}}
</div>
`);
const $tooltipOneTarget = this.$('.tooltip-one-target');
triggerTooltipTargetEvent($tooltipOneTarget, 'mouseenter');
assertTooltipVisible(assert, {selector: '.tooltip-one'});
assertTooltipNotRendered(assert, {selector: '.tooltip-two'});
This addon aims to meet 508 compliance.
Elements with tooltips are given a tabindex attribute and when the element receives focus, the tooltip with show.
Additionally, the aria-describedby, title, id, and role attributes are managed by this addon.
There is always room for improvement and PRs to improve accessibility are welcome.
All PRs and issues are welcome.
git clone https://github.com/sir-dunxalot/ember-tooltips.gitcd ember-tooltipsnpm install && bower installember sember test,ember try:testall, or the/testsroute
Please include tests and documentation updates with any new features.
You do not need to bump the version when you have a PR.
To release an update to the demo app:
git checkout master # make sure you're on master branch
ember github-pages:commit --message "Some commit message" # Builds the app
git push origin gh-pages:gh-pages # Deploys the app