@@ -53,11 +53,85 @@ def tooltip(
5353 those elements, wrap the object in a :func:`~shiny.ui.tags.div` or
5454 :func:`~shiny.ui.tags.span`.
5555
56+ Accessibility of Tooltip Triggers
57+ ---------------------------------
58+
59+ Because the user needs to interact with the `trigger` element to see the `tooltip`,
60+ it's best practice to use an element that is typically accessible via keyboard
61+ interactions, like a button or a link.
62+
63+ If you use a non-interactive element, like a `<span>` or text, `tooltip()` will
64+ automatically add the `tabindex="0"` attribute to the trigger element to make sure
65+ that users can reach the element with the keyboard. This means that in most cases
66+ you can use any element you want as the trigger.
67+
68+ One place where it's important to consider the accessibility of the trigger is when
69+ using an icon without any accompanying text. In these cases, many icon elements are
70+ created with the assumption that the icon is decorative, which will make it
71+ inaccessible to users of assistive technologies.
72+
73+ When using an icon as the primary trigger, ensure that the icon does not have
74+ `aria-hidden="true"` or `role="presentation"` attributes. Icon packages typically
75+ provide a way to specify a title for the icon, as well as a way to specify that the
76+ icon is not decorative. The title should be a short description of the purpose of
77+ the trigger, rather than a description of the icon itself.
78+
79+ For example:
80+
81+ ```python
82+ icon_title = "About tooltips"
83+ def bs_info_icon(title: str):
84+ # Enhanced from https://rstudio.github.io/bsicons/ via `bsicons::bs_icon("info-circle", title = icon_title)`
85+ return ui.HTML(f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" class="bi bi-info-circle " style="height:1em;width:1em;fill:currentColor;" aria-hidden="true" role="img" ><title>{title}</title><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"></path><path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"></path></svg>')
86+
87+ ui.tooltip(
88+ bs_info_icon(icon_title),
89+ "Text shown in the tooltip."
90+ )
91+ ```
92+
93+ ```python
94+ icon_title = "About tooltips"
95+ def fa_info_circle(title: str):
96+ # Enhanced from https://rstudio.github.io/fontawesome/ via `fontawesome::fa("info-circle", a11y = "sem", title = icon_title)`
97+ return ui.HTML(f'<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><title>{title}</title><path d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512zM216 336h24V272H216c-13.3 0-24-10.7-24-24s10.7-24 24-24h48c13.3 0 24 10.7 24 24v88h8c13.3 0 24 10.7 24 24s-10.7 24-24 24H216c-13.3 0-24-10.7-24-24s10.7-24 24-24zm40-208a32 32 0 1 1 0 64 32 32 0 1 1 0-64z"/></svg>')
98+ ui.tooltip(
99+ fa_info_circle(icon_title),
100+ "Text shown in the tooltip."
101+ )
102+ ```
103+
56104 See Also
57105 --------
58106
59107 * [Bootstrap tooltips documentation](https://getbootstrap.com/docs/5.2/components/tooltips/)
60108 """
109+
110+ # * If you're using [bsicons::bs_icon()], provide a `title`.
111+ # * If you're using [fontawesome::fa()], set `a11y = "sem"` and provide a `title`.
112+
113+ # Theming/Styling
114+ # ---------------
115+ #
116+ # Like other bslib components, tooltips can be themed by supplying [relevant theming
117+ # variables](https://rstudio.github.io/bslib/articles/bs5-variables.html#tooltip-bg)
118+ # to [bs_theme()], which effects styling of every tooltip on the page. To style a
119+ # _specific_ tooltip differently from other tooltips, utilize the `customClass`
120+ # option:
121+ #
122+ # ```
123+ # tooltip(
124+ # "Trigger", "Tooltip message",
125+ # options = {"customClass": "my-pop"}
126+ # )
127+ # ```
128+ #
129+ # And then add relevant rules to [bs_theme()] via [bs_add_rules()]:
130+ #
131+ # ```
132+ # bs_theme() |> bs_add_rules(".my-pop { max-width: none; }")
133+ # ```
134+
61135 attrs , children = consolidate_attrs (* args , ** kwargs )
62136
63137 if len (children ) == 0 :
0 commit comments