Class: Primer::Alpha::Tooltip

Inherits:
Component
  • Object
show all
Defined in:
app/components/primer/alpha/tooltip.rb

Overview

‘Tooltip` only appears on mouse hover or keyboard focus and contain a label or description text. Use tooltips sparingly and as a last resort. Use tooltips as a last resort. Please consider [Tooltips alternatives](primer.style/design/accessibility/tooltip-alternatives).

When using a tooltip, follow the provided guidelines to avoid accessibility issues:

  • Tooltips should contain only **non-essential text**. Tooltips can easily be missed and are not accessible on touch devices so never use tooltips to convey critical information.

  • ‘Tooltip` should be rendered through the API of <%= link_to_component(Primer::ButtonComponent)%>, <%= link_to_component(Primer::Beta::Link)%>, or <%= link_to_component(Primer::IconButton)%>. Avoid using `Tooltip` a standalone component unless absolutely necessary (and only on interactive elements).

  • Tooltip text must be brief and concise even when used to display a description.

  • Tooltips can only hold string content.

  • Tooltips are not allowed on ‘disabled` elements because such elements are not keyboard-accessible. If you must set a tooltip on a disabled element, use `aria-disabled=“true”` instead and programmatically disable the element.

  • **Never set tooltips on static, non-interactive elements** like ‘span` or `div`. Tooltips should only be used on interactive elements like buttons or links to avoid excluding keyboard-only

and screen reader users. Use of tooltips through <%= link_to_component(Primer::Beta::Button) %>, <%= link_to_component(Primer::Beta::Link) %>, or <%= link_to_component(Primer::Beta::IconButton) %> will guarantee this.

  • If you must use ‘Tooltip` as a standalone component, place it immediately after the trigger element in the DOM. This allows screen reader users to navigate to the tooltip and copy its contents if desired. content.

Semantically, a tooltip will either act an accessible name or an accessible description for the element that it is associated with resulting in either a ‘aria-labelledby` or an `aria-describedby` association. The `type` drastically changes semantics and screen reader behavior so follow these guidelines carefully:

  • When there is already a visible label text on the trigger element, the tooltip is likely intended be supplementary, so set ‘type: :description`.

The majority of tooltips will fall under this category.

  • When there is no visible text on the trigger element and the tooltip content is appropriate as a label for the element, set ‘type: :label`.

‘label` type is usually only appropriate for an icon-only control.

Constant Summary collapse

DIRECTION_DEFAULT = 
:s
DIRECTION_OPTIONS = 
[DIRECTION_DEFAULT, :n, :e, :w, :ne, :nw, :se, :sw].freeze
TYPE_FALLBACK = 
:description
TYPE_OPTIONS = 
[:label, :description].freeze

Constants inherited from Component

Component::INVALID_ARIA_LABEL_TAGS

Constants included from Status::Dsl

Status::Dsl::STATUSES

Constants included from ViewHelper

ViewHelper::HELPERS

Constants included from TestSelectorHelper

TestSelectorHelper::TEST_SELECTOR_TAG

Constants included from FetchOrFallbackHelper

FetchOrFallbackHelper::InvalidValueError

Constants included from Primer::AttributesHelper

Primer::AttributesHelper::PLURAL_ARIA_ATTRIBUTES, Primer::AttributesHelper::PLURAL_DATA_ATTRIBUTES

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods inherited from Component

deprecated?, generate_id

Methods included from JoinStyleArgumentsHelper

#join_style_arguments

Methods included from TestSelectorHelper

#add_test_selector

Methods included from FetchOrFallbackHelper

#fetch_or_fallback, #fetch_or_fallback_boolean, #silence_deprecations?

Methods included from ClassNameHelper

#class_names

Methods included from Primer::AttributesHelper

#aria, #data, #merge_aria, #merge_data, #merge_prefixed_attribute_hashes

Constructor Details

#initialize(type:, for_id:, text:, direction: DIRECTION_DEFAULT, **system_arguments) ⇒ Tooltip

Returns a new instance of Tooltip.

Parameters:

  • for_id (String) —

    The ID of the element that the tooltip should be attached to.

  • type (Symbol) —

    <%= one_of(Primer::Alpha::Tooltip::TYPE_OPTIONS) %>

  • direction (Symbol) (defaults to: DIRECTION_DEFAULT) —

    <%= one_of(Primer::Alpha::Tooltip::DIRECTION_OPTIONS) %>

  • text (String) —

    The text content of the tooltip. This should be brief and no longer than a sentence.

  • system_arguments (Hash) —

    <%= link_to_system_arguments_docs %>

Raises:

  • (TypeError) 


39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'app/components/primer/alpha/tooltip.rb', line 39

def initialize(type:, for_id:, text:, direction: DIRECTION_DEFAULT, **system_arguments)
  raise TypeError, "tooltip text must be a string" unless text.is_a?(String)

  @text = text
  @system_arguments = system_arguments
  @id = @system_arguments[:id] ||= self.class.generate_id
  @system_arguments[:tag] = :"tool-tip"
  @system_arguments[:for] = for_id
  @system_arguments[:popover] = "manual"
  @system_arguments[:classes] = class_names(
    @system_arguments[:classes],
    "sr-only"
  )
  @system_arguments[:position] = :absolute
  @system_arguments[:"data-direction"] = fetch_or_fallback(DIRECTION_OPTIONS, direction, DIRECTION_DEFAULT).to_s
  @system_arguments[:"data-type"] = fetch_or_fallback(TYPE_OPTIONS, type, TYPE_FALLBACK).to_s
end

Instance Attribute Details

#id ⇒ Object (readonly)

Returns the value of attribute id.



32
33
34
 
# File 'app/components/primer/alpha/tooltip.rb', line 32

def id
  @id
end

Instance Method Details

#call ⇒ Object 



57
58
59
 
# File 'app/components/primer/alpha/tooltip.rb', line 57

def call
  render(Primer::BaseComponent.new(**@system_arguments)) { @text }
end