Ember-tooltips

Render tooltips on components and other HTML elements using HTMLBars.

Installation

ember install ember-tooltips

Documentation

Documentation for usage is below:

• Demo
• 1.0.0 Release
• Usage
  • tooltip-on-component
  • tooltip-on-element
• Options
  • Setting defaults
• Actions
• Accessibility

1.0.0 Release

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.

Usage

Tooltip on Component

The easiest way to add a tooltip to any component is with the {{tooltip-on-component}} component:

{{#my-component}}
  Hover for more info

  {{#tooltip-on-component}}
    Here is the info in a tooltip!
  {{/tooltip-on-component}}
{{/my-component}}

Options can be set on the {{tooltip-on-component}} as attributes:

{{#my-component}}
  Click for more info

  {{#tooltip-on-component event='click'}}
    This info will show on click!
  {{/tooltip-on-component}}
{{/my-component}}

Documentation for supported options is located here.

Tooltip on Element

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:

<div>
  Hover for more info

  {{#tooltip-on-element}}
    Here is the info in a tooltip!
  {{/tooltip-on-element}}
</div>

You can also specify the ID of the element to attach the tooltip to:

{{input id='has-info-tooltip'}}

{{#tooltip-on-element target='#has-info-tooltip'}}
  Here is some more info
{{/tooltip-on-element}}

The target property must be an ID, including the #.

Options

Options are set as attributes on the tooltip components. Current tooltip properties this addon supports are:

• class
• delay
• delayOnChange
• duration
• effect
• event
• hideOn
• keepInWindow
• side
• showOn
• spacing
• tooltipIsVisible

Class

Type	String
Default	none

Adds a class to any tooltip:

{{tooltip-on-component class='tooltip-warning'}}

Delay

Type	Number
Default	0

Delays showing the tooltip by the given number of milliseconds.

{{!--Delays the show animation by 500ms--}}

{{tooltip-on-component delay=500}}

This does not affect the hiding of the tooltip. See also, delayOnChange.

Delay on change

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:

{{!--Forces delay to be enforced when the user skips
between elements with tooltips--}}

{{tooltip-on-component delayOnChange=true}}

Duration

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.

{{!-- Closes the tooltip after 1000ms--}}

{{tooltip-on-component duration=1000}}

Effect

Type	String
Default	'slide'

Sets the animation used to show and hide the tooltip. Possible options are:

• 'fade'
• 'slide'
• 'none'

{{tooltip-on-component effect='slide'}}

Event

Type	String
Default	'hover'

The event that the tooltip will hide and show for. Possible options are:

• 'hover'
• 'click'
• 'focus' (hides on blur)
• 'none'

{{tooltip-on-component event='click'}}

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 tooltipIsVisible property, documented here.

Hide on

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 tooltip will hide on mouseleave, NOT click--}}

{{tooltip-on-component
  event='click'
  hideOn='mouseleave'
}}

This does not affect the event the tooltip shows on. That is set by the showOn option. This will override the event property.

Keep in window

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.

{{!--Forces the tooltip to stay on the left even if
it will render off-screen--}}

{{tooltip-on-component
  keepInWindow=false
  side='right'
}}

Side

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'

{{!--The tooltip will render on the right of the target element--}}

{{tooltip-on-component
  side='right'
}}

Show on

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 tooltip will show on click, NOT hover--}}

{{tooltip-on-component
  showOn='click'
}}

This does not affect the event the tooltip hides on. That is set by the hideOn option. This will override the event property.

Spacing

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.

{{!--Render the tooltip 20px from the target element--}}
{{tooltip-on-component spacing=20}}

Tooltip is visible

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.

{{!--Binds the tooltip visibility to the showTooltip property--}}
{{tooltip-on-component tooltipIsVisible=showTooltip}}

Setting Defaults

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',
});

Actions

Four actions are available for you to hook onto through the tooltip lifecycle:

{{tooltip-on-component
  onTooltipDestroy='onTooltipDestroy'
  onTooltipHide='onTooltipHide'
  onTooltipRender='onTooltipRender'
  onTooltipShow='onTooltipShow'
}}

Accessibility

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.

Development

All PRs and issues are welcome.

• git clone https://github.com/sir-dunxalot/ember-tooltips.git
• cd ember-tooltips
• npm install && bower install
• ember s
• ember test, ember try:testall, or the /tests route

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