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.

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

  • Tooltip text should be brief and to the point. The tooltip content must be a string.

  • 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.

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

Instance Method Summary collapse

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

Constructor Details

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

Returns a new instance of Tooltip.

Examples:

As a description for an icon-only button

@description
  If the tooltip content provides supplementary description, set `type: :description` to establish an `aria-describedby` relationship.
  The trigger element should also have a _concise_ accessible label via `aria-label`.
@code
  <%= render(Primer::IconButton.new(id: "bold-button-0", icon: :bold, "aria-label": "Bold")) %>
  <%= render(Primer::Alpha::Tooltip.new(for_id: "bold-button-0", type: :description, text: "Add bold text", direction: :ne)) %>

As a label for an icon-only button

@description
  If the tooltip labels the icon-only button, set `type: :label`. This tooltip content becomes the accessible name for the button.
@code
  <%= render(Primer::ButtonComponent.new(id: "like-button")) { "👍" } %>
  <%= render(Primer::Alpha::Tooltip.new(for_id: "like-button", type: :label, text: "Like", direction: :n)) %>

As a description for a button with visible label

@description
  If the button already has visible label text, the tooltip content is likely supplementary so set `type: :description`.
@code
  <%= render(Primer::ButtonComponent.new(id: "save-button", scheme: :primary)) { "Save" } %>
  <%= render(Primer::Alpha::Tooltip.new(for_id: "save-button", type: :description, text: "This will immediately impact all organization members", direction: :ne)) %>

With direction

@description
  Set direction of tooltip with `direction`. The tooltip is responsive and will automatically adjust direction to avoid cutting off.
@code
  <%= render(Primer::ButtonComponent.new(id: "North", m: 2)) { "North" } %>
  <%= render(Primer::Alpha::Tooltip.new(for_id: "North", type: :description, text: "This is a North-facing tooltip, and is responsive.", direction: :n)) %>
  <%= render(Primer::ButtonComponent.new(id: "South", m: 2)) { "South" } %>
  <%= render(Primer::Alpha::Tooltip.new(for_id: "South", type: :description, text: "This is a South-facing tooltip and is responsive.", direction: :s)) %>
  <%= render(Primer::ButtonComponent.new(id: "East", m: 2)) { "East" } %>
  <%= render(Primer::Alpha::Tooltip.new(for_id: "East", type: :description, text: "This is a East-facing tooltip and is responsive.", direction: :e)) %>
  <%= render(Primer::ButtonComponent.new(id: "West", m: 2)) { "West" } %>
  <%= render(Primer::Alpha::Tooltip.new(for_id: "West", type: :description, text: "This is a West-facing tooltip and is responsive.", direction: :w)) %>
  <%= render(Primer::ButtonComponent.new(id: "Northeast", m: 2)) { "Northeast" } %>
  <%= render(Primer::Alpha::Tooltip.new(for_id: "Northeast", type: :description, text: "This is a Northeast-facing tooltip and is responsive.", direction: :ne)) %>
  <%= render(Primer::ButtonComponent.new(id: "Southeast", m: 2)) { "Southeast" } %>
  <%= render(Primer::Alpha::Tooltip.new(for_id: "Southeast", type: :description, text: "This is a Southeast-facing tooltip and is responsive.", direction: :se)) %>
  <%= render(Primer::ButtonComponent.new(id: "Northwest", m: 2)) { "Northwest" } %>
  <%= render(Primer::Alpha::Tooltip.new(for_id: "Northwest", type: :description, text: "This is a Northwest-facing tooltip and is responsive.", direction: :nw)) %>
  <%= render(Primer::ButtonComponent.new(id: "Southwest", m: 2)) { "Southwest" } %>
  <%= render(Primer::Alpha::Tooltip.new(for_id: "Southwest", type: :description, text: "This is a Southwest-facing tooltip and is responsive.", direction: :sw)) %>

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) 


78
79
80
81
82
83
84
85
86
87
88
 
# File 'app/components/primer/alpha/tooltip.rb', line 78

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
  @system_arguments[:hidden] = true
  @system_arguments[:tag] = :"tool-tip"
  @system_arguments[:for] = for_id
  @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 Method Details

#call ⇒ Object 



90
91
92
 
# File 'app/components/primer/alpha/tooltip.rb', line 90

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