` there would end the paragraph. - For a profile preview, `.hover-card-header` puts an [avatar](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/avatar) beside a `.hover-card-body`, which stacks a `.hover-card-title`, a `.hover-card-description` and a muted `.hover-card-meta` line with an icon. - The trigger stays an ordinary link: clicking or tapping it follows it. The card only adds a preview of what is there, so nothing must be reachable through the card alone. ## Opening and closing - A mouse or pen resting on the trigger opens the card after `700ms`, so it doesn't flash while the pointer crosses the page. Leaving before then opens nothing. - Once the pointer has left both the trigger and the card, the card closes after `300ms`. The pointer can travel from the trigger onto the card, across the gap, to select text or follow a link in it. - Keyboard focus on the trigger opens it at once. The card stays open while focus is inside it and closes when focus leaves. A mouse click that focuses the trigger doesn't open it. - Touch never opens it: on a phone the link simply navigates. - `Esc` closes it. The behaviour sets `data-open` on the wrapper while the card is open. Without JavaScript, CSS opens it on hover and keyboard focus, with the same delays. ## Side Cards open below their trigger. `.hover-card-content-top`, `.hover-card-content-right` and `.hover-card-content-left` put them on another side. ```html Top Opens above the trigger. Left Opens to the left. Right Opens to the right. Bottom Opens below the trigger (the default). ``` If the card would stick out of the window on its side, it opens on the opposite side instead, provided that side has more room: a card set to open above a link at the top of the screen opens below it. `data-side` on the card says which side it opened on. Like any absolutely positioned element, it is still clipped by an ancestor with `overflow: hidden`. ## Alignment A card is centred on its trigger. `.hover-card-content-start` lines it up with the trigger's start edge and `.hover-card-content-end` with its end edge (the top and bottom edges for cards on the left or right). ```html Start Aligned to the start edge of its trigger. Center Aligned to the centre of its trigger. End Aligned to the end edge of its trigger. ``` ## Size Cards are `16rem` wide. `.hover-card-content-sm` makes them `12rem` and `.hover-card-content-lg` `20rem`; any `w-*` utility sets another width. They never get wider than the window. ```html Small Small A hover card with .hover-card-content-sm. Default Default A hover card with the default width. Large Large A hover card with .hover-card-content-lg. ``` ## Offset The gap between trigger and card is `--hover-card-offset`, `0.25rem` by default. Set it on the wrapper or any ancestor; the invisible bridge the pointer crosses grows with it. ```html 1rem away Opens 1rem below its trigger. ``` ## In a paragraph The usual home of a hover card: names and references in running text, each previewing the page it links to. ```html
This release was written by Ada Moreno Ada Moreno Maintainer. Works on the engine and the docs plugin. and reviewed by Sam Okafor Sam Okafor Reviews accessibility across the component library. . It closes three issues.
``` ## Delays `--hover-card-open-delay` (`700ms`) is how long the pointer must rest on the trigger, and `--hover-card-close-delay` (`300ms`) how long the card waits after the pointer has left. Set them on the wrapper or any ancestor, in `ms` or `s`. Keyboard focus ignores the open delay. ```html Quick Opens after 100ms. Lingering Stays for a second after the pointer leaves. ``` ## Keyboard | Key | Action | | --- | --- | | `Tab` | Focusing the trigger opens the card. The next `Tab` moves into the card's links, if it has any; leaving the card closes it. | | `Enter` | Follows the trigger link, as usual. | | `Esc` | Closes the card. Focus inside the card returns to the trigger. It opens again when the pointer comes back or focus returns to the trigger. | ## Accessibility - A hover card is for sighted mouse and keyboard users. The trigger is a real link that leads to the same information, so everyone else loses nothing. - The card has no role and isn't a dialog: it doesn't take focus or trap it, and opening it isn't announced. - While closed it is hidden with `visibility`, so screen readers and `Tab` skip it. While open it is ordinary content after the link, which keyboard users can tab into. - The trigger isn't linked to the card with `aria-describedby`, as a [tooltip](https://susonwaiba.github.io/htmx-ui/docs/v0.2/components/tooltip) is: a profile card is too long to read out after every mention. For a short card, add it yourself: give the card an `id` and put it in the trigger's `aria-describedby`. - It meets WCAG 1.4.13 (content on hover or focus): it can be dismissed with `Esc` without moving the pointer, the pointer can move onto it, and it stays until the pointer or focus leaves. - With reduced motion, the card fades without sliding or zooming. ## With htmx The card fires `hover-card:open` and `hover-card:close` (they bubble) each time it opens and closes. Load the preview from the server the first time it opens with `hx-trigger="hover-card:open once"` on the card, so a page full of mentions doesn't fetch every profile up front: ```html @htmx-ui Loading profile… ``` The server returns the card's inner markup, which replaces the placeholder. Components in it are initialised as usual, since htmx-ui runs its initialisers on new content. ## Reference | Class / attribute | Description | | --- | --- | | `.hover-card` | Wrapper around the trigger and the card. Add data-hover-card. | | `.hover-card-content` | The card: below the trigger, centred, 16rem wide. Add data-hover-card-content. | | `.hover-card-content-top / -right / -bottom / -left` | The side it opens on (bottom by default). | | `.hover-card-content-start / -end` | Align with the trigger's start or end edge (centred by default). | | `.hover-card-content-sm / -lg` | 12rem / 20rem wide. | | `.hover-card-header` | An avatar beside the body. | | `.hover-card-body` | Stacks the title, description and meta line. | | `.hover-card-title` | The name or title, in bold. | | `.hover-card-description` | A line or two of text. | | `.hover-card-meta` | A small muted line with an icon, such as a join date. | | `[data-hover-card]` | Behaviour: delays, keyboard focus, Escape, flipping, events. | | `[data-hover-card-trigger]` | Marks the trigger when it isn't the first link inside. | | `[data-hover-card-content]` | Marks the card. | | `[data-open]` | Set on the wrapper while the card is open. | | `[data-side]` | Set on the card when it opens: the side it opened on, after any flip. | | `--hover-card-open-delay` | How long the pointer rests on the trigger before the card opens (700ms). | | `--hover-card-close-delay` | How long the card stays after the pointer leaves (300ms). | | `--hover-card-offset` | Gap between trigger and card (0.25rem). | | `hover-card:open / hover-card:close` | Events fired on the card (bubbling) when it opens and closes. |
