Tooltips 1.2.2

Lightweight text hints on hover/focus. Available as the <velin-tooltip> web component or the pure-CSS .velin-tooltip class. Deutsch: Tooltipps

Maturity: Documented as stable in VelinStyle 1.2.0. Design Intelligence (plan / review / agent meta) is separate and beta / foundation where noted.

When to use

Short, supplementary labels for icon-only controls or truncated text.
Prefer <velin-tooltip> when you need viewport flip and aria-describedby wiring.
Prefer the CSS pattern for static tips that only need hover/focus-within.

When not

Rich content, forms, or links inside the tip — use Popover.
Essential instructions the user must read without hovering — put them in the page or an Alert.
Do not invent a flip attribute or data-tooltip — those are not part of the 1.2.0 API.

Wrap the trigger and a .velin-tooltip__content child. Optional .velin-tooltip--bottom places the tip below.

<span class="velin-tooltip" tabindex="0">
  Hover me
  <span class="velin-tooltip__content">Hello from a tooltip!</span>
</span>

<span class="velin-tooltip velin-tooltip--bottom" tabindex="0">
  Bottom
  <span class="velin-tooltip__content">Shown below</span>
</span>

Web component

Use <velin-tooltip> with content and optional placement (top default, bottom, start, end). Slot the focusable trigger.

<velin-tooltip content="Tooltip text" placement="top">
  <button type="button" class="velin-btn velin-btn--secondary">Hover / focus</button>
</velin-tooltip>

Flip behaviour

Flip is automatic on show for top/bottom when the tip would leave the viewport. There is no flip attribute — do not add one.

Accessibility

Tip panel uses role="tooltip".
While visible, the slotted trigger gets aria-describedby pointing at the tip id.
Shows on pointer enter and focus-in; hides on leave, focus-out, or Escape.
CSS-only tips need a focusable trigger (tabindex="0" or a control) so keyboard users can reveal them via :focus-within.
content is HTML-escaped before render.

API

Attributes (`<velin-tooltip>`)

Attribute	Type	Description
`content`	String	Observed — tip text (escaped). Use `content`, not `text` (that attribute is ignored).
`placement`	String	Observed — `top` (default), `bottom`, `start`, `end`
`visible`	Boolean	Set by the component while open (not a public show API)

Slots & parts

Name	Kind	Description
(default)	Slot	Trigger element
`tip`	CSS part	Shadow tip surface

No public methods or events. CSS pattern: .velin-tooltip, .velin-tooltip__content, .velin-tooltip--bottom.

Best practices & pitfalls

Keep tip text short; never put interactive content in a tooltip.
Prefer logical start/end placements on the WC for RTL-friendly UIs.
Do not use deprecated <velin-tooltip-wc> in new markup.
Do not invent text="…" on <velin-tooltip> — the tip string is always content.

Popover — rich anchored panels
Dropdown — action menus
A11y patterns

Legacy `*-wc` tags

<velin-tooltip-wc> and <velin-stepper-wc> remain registered as deprecated aliases. Prefer <velin-tooltip> and <velin-stepper> in new markup.