UNPKG

11.7 kBTypeScriptView Raw
1import * as Popper from "@popperjs/core";
2import BaseComponent, { GetInstanceFactory, GetOrCreateInstanceFactory } from "./base-component";
3
4declare class Tooltip extends BaseComponent {
5 static getInstance: GetInstanceFactory<Tooltip>;
6
7 /**
8 * Static method which allows you to get the tooltip instance associated with
9 * a DOM element, or create a new one in case it wasn’t initialised
10 */
11 static getOrCreateInstance: GetOrCreateInstanceFactory<Tooltip>;
12
13 static jQueryInterface: Tooltip.jQueryInterface;
14
15 static NAME: "tooltip";
16
17 /**
18 * Default settings of this plugin
19 *
20 * @link https://getbootstrap.com/docs/5.0/getting-started/javascript/#default-settings
21 */
22 static Default: Tooltip.Options;
23
24 static Event: Record<
25 | "CLICK"
26 | "FOCUSIN"
27 | "FOCUSOUT"
28 | "HIDDEN"
29 | "HIDE"
30 | "INSERTED"
31 | "MOUSEENTER"
32 | "MOUSELEAVE"
33 | "SHOW"
34 | "SHOWN",
35 string
36 >;
37
38 static DefaultType: Record<keyof Tooltip.Options, string>;
39 constructor(element: string | Element, options?: Partial<Tooltip.Options>);
40
41 static SetContentFunction: Tooltip.SetContentFunction;
42
43 /**
44 * Reveals an element’s tooltip. Returns to the caller before the
45 * tooltip has actually been shown (i.e. before the shown.bs.tooltip
46 * event occurs). This is considered a “manual” triggering of the
47 * tooltip. Tooltips with zero-length titles are never displayed.
48 */
49 show(): void;
50
51 /**
52 * Hides an element’s tooltip. Returns to the caller before the tooltip
53 * has actually been hidden (i.e. before the hidden.bs.tooltip event
54 * occurs). This is considered a “manual” triggering of the tooltip.
55 */
56 hide(): void;
57
58 /**
59 * Toggles an element’s tooltip. Returns to the caller before the
60 * tooltip has actually been shown or hidden (i.e. before the
61 * shown.bs.tooltip or hidden.bs.tooltip event occurs). This is
62 * considered a “manual” triggering of the tooltip.
63 */
64 toggle(event?: any): void;
65
66 /**
67 * Gives an element’s tooltip the ability to be shown. Tooltips are
68 * enabled by default.
69 */
70 enable(): void;
71
72 /**
73 * Removes the ability for an element’s tooltip to be shown. The tooltip
74 * will only be able to be shown if it is re-enabled.
75 */
76 disable(): void;
77
78 /**
79 * Toggles the ability for an element’s tooltip to be shown or hidden.
80 */
81 toggleEnabled(): void;
82
83 /**
84 * Updates the position of an element’s tooltip.
85 */
86 update(): void;
87
88 /**
89 * Gives a way to change the tooltip’s content after its initialization.
90 */
91 setContent(content?: Record<string, string | Element | Tooltip.SetContentFunction | null>): void;
92}
93
94declare namespace Tooltip {
95 enum Events {
96 /**
97 * This event fires immediately when the show instance method is called.
98 */
99 show = "show.bs.tooltip",
100
101 /**
102 * This event is fired when the tooltip has been made visible to the
103 * user (will wait for CSS transitions to complete).
104 */
105 shown = "shown.bs.tooltip",
106
107 /**
108 * This event is fired immediately when the hide instance method has
109 * been called.
110 */
111 hide = "hide.bs.tooltip",
112
113 /**
114 * This event is fired when the tooltip has finished being hidden from
115 * the user (will wait for CSS transitions to complete).
116 */
117 hidden = "hidden.bs.tooltip",
118
119 /**
120 * This event is fired after the show.bs.tooltip event when the tooltip
121 * template has been added to the DOM.
122 */
123 inserted = "inserted.bs.tooltip",
124 }
125
126 type Offset = [number, number];
127
128 type OffsetFunction = () => Offset;
129
130 type PopoverPlacement = "auto" | "top" | "bottom" | "left" | "right";
131
132 type PopperConfigFunction = (defaultBsPopperConfig: Popper.Options) => Partial<Popper.Options>;
133
134 interface Options {
135 /**
136 * Apply a CSS fade transition to the tooltip
137 *
138 * @default true
139 */
140 animation: boolean;
141
142 /**
143 * Appends the tooltip to a specific element. Example: container:
144 * 'body'. This option is particularly useful in that it allows you to
145 * position the tooltip in the flow of the document near the triggering
146 * element - which will prevent the tooltip from floating away from the
147 * triggering element during a window resize.
148 *
149 * @default false
150 */
151 container: string | Element | false;
152
153 /**
154 * Delay showing and hiding the popover (ms) - does not apply to manual
155 * trigger type
156 *
157 * If a number is supplied, delay is applied to both hide/show
158 *
159 * @default 0
160 */
161 delay: number | { show: number; hide: number };
162
163 /**
164 * Allow HTML in the tooltip.
165 *
166 * If true, HTML tags in the tooltip's title will be rendered in the
167 * tooltip. If false, innerText property will be used to insert content
168 * into the DOM.
169 *
170 * Use text if you're worried about XSS attacks.
171 *
172 * @default false
173 */
174 html: boolean;
175
176 /**
177 * How to position the popover - auto | top | bottom | left | right.
178 * When auto is specified, it will dynamically reorient the popover.
179 *
180 * When a function is used to determine the placement, it is called with
181 * the popover DOM node as its first argument and the triggering element
182 * DOM node as its second. The this context is set to the popover
183 * instance.
184 *
185 * @default 'top'
186 */
187 placement: PopoverPlacement | (() => PopoverPlacement);
188
189 /**
190 * If a selector is provided, tooltip objects will be delegated to the
191 * specified targets. In practice, this is used to also apply tooltips
192 * to dynamically added DOM elements (jQuery.on support).
193 *
194 * @default false
195 */
196 selector: string | false;
197
198 /**
199 * Base HTML to use when creating the tooltip.
200 *
201 * The tooltip's title will be injected into the .tooltip-inner.
202 *
203 * .tooltip-arrow will become the tooltip's arrow.
204 *
205 * The outermost wrapper element should have the .tooltip class and
206 * role="tooltip".
207 *
208 * @default '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'
209 */
210 template: string;
211
212 /**
213 * Default title value if title attribute isn't present.
214 *
215 * If a function is given, it will be called with its this reference set
216 * to the element that the popover is attached to.
217 *
218 * @default ''
219 */
220 title: string | Element | JQuery | ((this: HTMLElement) => string | Element | JQuery);
221
222 /**
223 * How tooltip is triggered - click | hover | focus | manual. You may
224 * pass multiple triggers; separate them with a space.
225 *
226 * 'manual' indicates that the tooltip will be triggered
227 * programmatically via the .tooltip('show'), .tooltip('hide') and
228 * .tooltip('toggle') methods; this value cannot be combined with any
229 * other trigger.
230 *
231 * 'hover' on its own will result in tooltips that cannot be triggered
232 * via the keyboard, and should only be used if alternative methods for
233 * conveying the same information for keyboard users is present.
234 *
235 * @default 'hover focus'
236 */
237 trigger:
238 | "click"
239 | "hover"
240 | "focus"
241 | "manual"
242 | "click hover"
243 | "click focus"
244 | "hover focus"
245 | "click hover focus";
246
247 /**
248 * Offset of the tooltip relative to its target.
249 *
250 * When a function is used to determine the offset, it is called with an
251 * object containing the popper placement, the reference, and popper
252 * rects as its first argument. The triggering element DOM node is
253 * passed as the second argument. The function must return an array with
254 * two numbers: [skidding, distance].
255 *
256 * @see {@link https://popper.js.org/docs/v2/modifiers/offset}
257 * @default [0, 0]
258 */
259 offset: Offset | string | OffsetFunction;
260
261 /**
262 * Allow to specify which position Popper will use on fallback.
263 *
264 * @see {@link https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements}
265 * @default ['top', 'right', 'bottom', 'left']
266 */
267 fallbackPlacements: string[];
268
269 /**
270 * Overflow constraint boundary of the popover. Accepts the values of
271 * 'viewport', 'window', 'scrollParent', or an HTMLElement reference
272 * (JavaScript only).
273 *
274 * @see {@link https://popper.js.org/docs/v1/#modifiers..preventOverflow.boundariesElement}
275 * @default 'scrollParent'
276 */
277 boundary: Popper.Boundary;
278
279 /**
280 * Add classes to the tooltip when it is shown. Note that these classes
281 * will be added in addition to any classes specified in the template.
282 * To add multiple classes, separate them with spaces: 'class-1
283 * class-2'.
284 *
285 * You can also pass a function that should return a single string
286 * containing additional class names.
287 *
288 * @default ''
289 */
290 customClass?: string | (() => string) | undefined;
291
292 /**
293 * Enable or disable the sanitization. If activated 'template' and
294 * 'title' options will be sanitized.
295 *
296 * @default true
297 */
298 sanitize: boolean;
299
300 /**
301 * Object which contains allowed attributes and tags
302 *
303 * @see {@link https://v5.getbootstrap.com/docs/5.0/getting-started/javascript/#sanitizer}
304 */
305 allowList: Record<keyof HTMLElementTagNameMap | "*", Array<string | RegExp>>;
306
307 /**
308 * Here you can supply your own sanitize function. This can be useful if
309 * you prefer to use a dedicated library to perform sanitization.
310 *
311 * @default null
312 */
313 // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
314 sanitizeFn: () => void | null;
315
316 /**
317 * To change Bootstrap's default Popper.js config
318 *
319 * When a function is used to create the Popper configuration, it's
320 * called with an object that contains the Bootstrap's default Popper
321 * configuration. It helps you use and merge the default with your own
322 * configuration. The function must return a configuration object for
323 * Popper.
324 *
325 * @see {@link https://popper.js.org/docs/v2}
326 * @default null
327 */
328 popperConfig: Partial<Popper.Options> | PopperConfigFunction | null;
329 }
330
331 type SetContentFunction = () => string | Element | (() => string | Element | null) | null;
332
333 type jQueryInterface = (
334 config?:
335 | Partial<Options>
336 | "show"
337 | "hide"
338 | "toggle"
339 | "enable"
340 | "disable"
341 | "toggleEnabled"
342 | "update"
343 | "setContent"
344 | "dispose",
345 ) => JQuery;
346}
347
348export default Tooltip;