Tooltip

Panoramica

Usa Tooltip per una breve spiegazione di un controllo o di testo troncato. Mantieni visibili le informazioni essenziali, assegna ai controlli un nome accessibile e usa Popover quando il contenuto contiene collegamenti, pulsanti o altri controlli.

Utilizzo

import { Button } from 'twenty-ui/primitives/input';
import { Tooltip } from 'twenty-ui/primitives/surfaces';
import { Text } from 'twenty-ui/primitives/typography';

export const ExportHelp = () => (
  <Tooltip content="Download the visible records as a CSV file" side="top">
    <Text render={<span />}>
      <Button>Export records</Button>
    </Text>
  </Tooltip>
);

Il componente di convenienza accetta un elemento trigger come children. Gli elementi nativi ricevono direttamente gli attributi del trigger, i gestori di eventi e il ref. I componenti trigger personalizzati devono inoltrarli tutti. Un elemento wrapper funziona anche con un componente che non inoltra ogni prop del trigger. Il passaggio del mouse apre il tooltip dopo delay millisecondi, che per impostazione predefinita è 600. Lo stato attivo della tastiera lo apre immediatamente. closeDelay è impostato su 0 per impostazione predefinita; il passaggio del mouse sul popup lo mantiene aperto, a meno che non sia impostato disableHoverablePopup. Esc lo chiude.

Stato controllato

Usa insieme open e onOpenChange quando l’applicazione gestisce la visibilità. Usa defaultOpen solo per impostare la visibilità iniziale di un tooltip non controllato.

import { useState } from 'react';
import { Button } from 'twenty-ui/primitives/input';
import { Tooltip } from 'twenty-ui/primitives/surfaces';

export const ControlledExportHelp = () => {
  const [open, setOpen] = useState(false);

  return (
    <Tooltip
      content="Download the visible records as a CSV file"
      open={open}
      onOpenChange={setOpen}
      delay={300}
    >
      <span>
        <Button>Export records</Button>
      </span>
    </Tooltip>
  );
};

Contenuto avanzato e composizione

La forma abbreviata accetta description e startIcon insieme a content. Il contenuto del nodo personalizzato viene visualizzato come fornito, a meno che una descrizione o un’icona non richieda il layout del titolo.

import { IconInfoCircle } from 'twenty-ui/icon';
import { Button } from 'twenty-ui/primitives/input';
import { Tooltip } from 'twenty-ui/primitives/surfaces';

export const ExportDetails = () => (
  <Tooltip
    content="Export visible records"
    description="Only records matching your current filters are included."
    startIcon={<IconInfoCircle />}
    arrow
  >
    <Button>Export records</Button>
  </Tooltip>
);

L’utilizzo composto espone ogni parte Base UI installata e il layout opzionale Tooltip.Body. Assembla esplicitamente il portale, il posizionamento, il popup e la freccia facoltativa. Popup esegue il rendering dei relativi elementi figlio così come forniti; Body fornisce lo stesso layout di titolo, descrizione e icona decorativa della forma abbreviata.

import { Button } from 'twenty-ui/primitives/input';
import { Tooltip } from 'twenty-ui/primitives/surfaces';

export const ComposedExportDetails = () => (
  <Tooltip.Provider delay={300} closeDelay={100} timeout={400}>
    <Tooltip.Root>
      <Tooltip.Trigger render={<Button>Export records</Button>} />
      <Tooltip.Portal>
        <Tooltip.Positioner side="inline-end" sideOffset={10} arrowPadding={8}>
          <Tooltip.Popup>
            <Tooltip.Arrow />
            <Tooltip.Viewport>
              <Tooltip.Body description="Only records matching your current filters are included.">
                Export visible records
              </Tooltip.Body>
            </Tooltip.Viewport>
          </Tooltip.Popup>
        </Tooltip.Positioner>
      </Tooltip.Portal>
    </Tooltip.Root>
  </Tooltip.Provider>
);

Parte	Destinazione di elementi nativi, prop e ref
`Root`	Coordinamento di stato e payload. Nessun nodo DOM, prop nativa o ref DOM. `actionsRef` espone `close` e `unmount`.
`Provider`	`delay`, `closeDelay` e `timeout` condivisi. Nessun nodo DOM o ref DOM.
`Trigger`	Un pulsante per impostazione predefinita. Le prop native, i gestori, `render` e il ref hanno come destinazione l’elemento trigger.
`Portal`	Il div del portale. Per impostazione predefinita usa il contenitore del tema, quindi il corpo del documento.
`Positioner`	Il div di posizionamento. Gestisce l’ancora, il lato fisico/logico, gli offset, la gestione delle collisioni, il posizionamento fisso e il padding della freccia.
`Popup`	Il div del popup. Gestisce contenuto, prop native, stili, `render` e ref.
`Body`	Il div body opzionale all’interno di Popup o Viewport. Le proprietà native, gli stili, `render` e la ref hanno come destinazione il relativo elemento radice.
`Arrow`	Il div della freccia all’interno di Popup.
`Viewport`	Il div facoltativo per le transizioni tra i payload dei trigger.

Tooltip.Body accetta nodi figli del titolo opzionali, description e startIcon. I titoli usano un peso medio; le descrizioni usano il colore secondario del tooltip, preservano le interruzioni di riga e vanno a capo per i testi lunghi. Ometti i nodi figli del titolo per un tooltip con sola descrizione. L’icona è decorativa e appare solo con un titolo. Body non aggiunge alcun ruolo tooltip, stile popup, dimensionamento o posizionamento. Il contenuto Popup arbitrario rimane supportato. Importa TooltipBodyProps da twenty-ui/primitives/surfaces quando tipizzi un wrapper. Ogni parte DOM accetta prop native, ref e composizione render di elementi o callback. Le prop native di primo livello della forma abbreviata, render e il ref hanno come destinazione Popup. Usa triggerProps, positionerProps e portalProps per personalizzare le altre destinazioni; queste sovrascrivono i valori predefiniti della forma abbreviata. I children forniscono l’elemento di rendering predefinito del trigger. Entrambe le forme mantengono lo stato Root controllato/non controllato e i dettagli degli eventi di callback Base UI, inclusi annullamento, motivo, evento originale e trigger attivo. Tooltip.createHandle\<TPayload>() collega i trigger separati a una delle due forme tramite handle. I children del Root composto o content della forma abbreviata possono essere una funzione che riceve il payload attivo tipizzato. Tooltip.Handle e il tipo pubblico TooltipHandle espongono il contratto dell’handle installato. Gli handle supportano open(triggerId) e close() imperativi mentre il relativo Root è montato.

Migrazione

Sostituisci content={<Tooltip.Content description={description} startIcon={icon}>title</Tooltip.Content>} con content={title} description={description} startIcon={icon}. Nell’uso composto, utilizza Tooltip.Body per il layout condiviso di titolo e descrizione oppure componi i tuoi contenuti. Tooltip.Content e TooltipContentProps vengono rimossi. Le prop di posizionamento Popup composto esistenti vengono spostate in Positioner. Avvolgilo in Portal, sposta container e keepMounted in Portal, mantieni maxWidth su Popup e sostituisci arrow con un elemento figlio Arrow. Quando necessario, mantieni esplicitamente la spaziatura precedente con sideOffset={10}. Il Positioner composto mantiene sideOffset={0} di Base UI. Per impostazione predefinita, entrambe le forme limitano Popup a 300 pixel.

Controlli disabilitati

I pulsanti nativi disabilitati non possono ricevere lo stato attivo della tastiera. Racchiudine uno in un trigger attivabile tramite tastiera affinché gli utenti possano scoprire perché l’azione non è disponibile.

import { Button } from 'twenty-ui/primitives/input';
import { Tooltip } from 'twenty-ui/primitives/surfaces';

export const UnavailableExport = () => (
  <Tooltip content="Select at least one record to export">
    <span tabIndex={0} aria-label="Export records unavailable">
      <Button disabled>Export records</Button>
    </span>
  </Tooltip>
);

L’impostazione di disabled sulla forma abbreviata o su Root disabilita il tooltip stesso. disabled del trigger disabilita l’interazione del tooltip di quel trigger. Disabilita il controllo nativo tramite le proprie prop o l’elemento di rendering di Trigger.

Posizionamento e testo in eccesso

La forma abbreviata usa per impostazione predefinita side="top", align="center" e sideOffset={10}. Sia i tooltip abbreviati sia quelli composti hanno una larghezza massima di 300 pixel, limitata dallo spazio disponibile accanto all’ancora. Passa maxWidth alla forma abbreviata o a Tooltip.Popup per scegliere un massimo diverso, incluse anteprime più ampie. Gli stili popup nativi rimangono disponibili per dimensioni personalizzate. Il posizionamento si adatta allo spazio disponibile. Un tooltip aperto si nasconde mentre la relativa ancora scorre fuori dalla visualizzazione, anche fuori da un contenitore di scorrimento. Usa arrow per una freccia e container per sovrascrivere la destinazione del portale del tema; consulta la tematizzazione. Usa OverflowingTextWithTooltip quando un’etichetta di testo deve mostrare il valore completo solo se troncata. Le relative prop esistenti text, tooltipContent e tooltipPlace restano disponibili.

Props

Il riferimento viene generato dai tipi di componenti pubblici. Sono accettati anche gli attributi popup nativi e i gestori di eventi.

RefObject<TooltipRootActions | null>

A ref to imperative actions.

unmount: Ends the closing phase of the tooltip after an externally controlled closing animation finishes. Call preventUnmountOnClose() in onOpenChange first, otherwise the tooltip completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal.
close: Closes the tooltip imperatively when called.

"center" | "end" | "start"

predefinito:"center"

Alignment relative to the trigger. Defaults to center.

number | OffsetFunction

predefinito:"0"

Offset along the alignment axis in pixels.

An explicit positioning anchor for the popup.

boolean

Displays an arrow pointing to the trigger. Defaults to false.

number

predefinito:"5"

Minimum distance from the arrow to the popup edges.

ReactElement<unknown, string | JSXElementConstructor<any>>

obbligatorio

A single trigger element. Custom components must forward their ref, native attributes, and event handlers.

string | ((state: TooltipPopupState) => string | undefined)

Additional CSS class for the popup.

number

predefinito:"0"

Delay in milliseconds before closing after hover ends. Defaults to 0.

boolean

predefinito:"true"

Whether the tooltip should close when this trigger is clicked.

CollisionAvoidance

Determines how to handle collisions when positioning the popup.side controls overflow on the preferred placement axis (top/bottom or left/right):

'flip': keep the requested side when it fits; otherwise try the opposite side (top and bottom, or left and right).
'shift': never change side; keep the requested side and move the popup within the clipping boundary so it stays visible.
'none': do not correct side-axis overflow.

align controls overflow on the alignment axis (start/center/end):

'flip': keep side, but swap start and end when the requested alignment overflows.
'shift': keep side and requested alignment, then nudge the popup along the alignment axis to fit.
'none': do not correct alignment-axis overflow.

fallbackAxisSide controls fallback behavior on the perpendicular axis when the preferred axis cannot fit:

'start': allow perpendicular fallback and try the logical start side first (top before bottom, or left before right in LTR).
'end': allow perpendicular fallback and try the logical end side first (bottom before top, or right before left in LTR).
'none': do not fallback to the perpendicular axis.

When side is 'shift', explicitly setting align only supports 'shift' or 'none'. If align is omitted, it defaults to 'flip'.

Boundary

predefinito:"clipping-ancestors"

An element or a rectangle that delimits the area that the popup is confined to.

Padding

predefinito:"5"

Additional space to maintain from the edge of the collision boundary.

Portal destination. Defaults to the current theme container.

ReactNode | PayloadChildRenderFunction<TPayload>

obbligatorio

Supplementary content, or a function receiving the active trigger payload. Strings and numbers use the shorthand title layout.

boolean

predefinito:"false"

Initial visibility when the tooltip manages its own state.

string | null

ID of the trigger that the tooltip is associated with. This is useful in conjunction with the defaultOpen prop to create an initially open tooltip.

number

predefinito:"600"

Delay in milliseconds before opening on hover. Defaults to 600.

ReactNode

Optional secondary text below the shorthand title.

boolean

predefinito:"false"

Whether to disable the popup from tracking any layout shift of its positioning anchor.

boolean

predefinito:"false"

Prevents the tooltip from opening.

Prevents hovering over the popup from keeping it open.

TooltipHandle<TPayload>

Connects detached triggers and preserves their typed payloads.

boolean

Keeps the popup mounted while closed.

MaxWidth<string | number>

Maximum popup width. Defaults to 300 pixels and is capped by the space available beside the anchor.

((open: boolean, eventDetails: TooltipRootChangeEventDetails) => void)

Receives the requested open state and unchanged Base UI event details, including reason, event, trigger and cancel().

((open: boolean) => void)

Event handler called after any animations complete when the tooltip is opened or closed.

boolean

Controlled visibility of the tooltip.

TooltipPortalProps

Full Portal props, including native props, ref and render. Overrides shorthand portal defaults.

TooltipPositionerProps

Full Positioner props, including native props, ref and render. Overrides shorthand placement defaults.

"absolute" | "fixed"

predefinito:"absolute"

CSS positioning method for the popup.

Ref<HTMLDivElement>

Ref forwarded to the popup element.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPopupState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

predefinito:"top"

Preferred side of the trigger. Defaults to top and may change to avoid collisions.

number | OffsetFunction

predefinito:"10"

Distance from the trigger in pixels. Defaults to 10.

ReactNode

Optional node before the shorthand title.

boolean

predefinito:"false"

Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.

CSSProperties | ((state: TooltipPopupState) => CSSProperties | undefined)

Inline styles for the popup.

"both" | "none" | "x" | "y"

predefinito:"none"

Determines which axis the tooltip should track the cursor on.

string | null

ID of the trigger that the tooltip is associated with. This is useful in conjunction with the open prop to create a controlled tooltip. There’s no need to specify this prop when the tooltip is uncontrolled (that is, when the open prop is not set).

TooltipTriggerProps<TPayload>

Full Trigger props, including native props, ref, render and payload. Overrides the shorthand trigger defaults.

boolean

Fades and slides the popup out when it closes instead of hiding it at once.

RefObject<TooltipRootActions | null>

A ref to imperative actions.

unmount: Ends the closing phase of the tooltip after an externally controlled closing animation finishes. Call preventUnmountOnClose() in onOpenChange first, otherwise the tooltip completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal.
close: Closes the tooltip imperatively when called.

ReactNode | PayloadChildRenderFunction<Payload>

Parts or a render function receiving the active trigger payload. Root renders no DOM node.

boolean

predefinito:"false"

Whether the tooltip is initially open.To render a controlled tooltip, use the open prop instead.

string | null

ID of the trigger that the tooltip is associated with. This is useful in conjunction with the defaultOpen prop to create an initially open tooltip.

boolean

predefinito:"false"

Whether the tooltip is disabled.

Whether the tooltip contents can be hovered without closing the tooltip.

TooltipHandle<Payload>

Connects detached triggers and imperative open/close actions.

((open: boolean, eventDetails: TooltipRootChangeEventDetails) => void)

Receives the requested open state and unchanged Base UI event details, including reason, event, trigger and cancel().

((open: boolean) => void)

Event handler called after any animations complete when the tooltip is opened or closed.

boolean

Whether the tooltip is currently open.

"both" | "none" | "x" | "y"

predefinito:"none"

Determines which axis the tooltip should track the cursor on.

string | null

Tooltip.Trigger

string | ((state: TooltipTriggerState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

number

predefinito:"0"

How long to wait before closing the tooltip. Specified in milliseconds.

boolean

predefinito:"true"

Whether the tooltip should close when this trigger is clicked.

number

predefinito:"600"

How long to wait before opening the tooltip on hover. Specified in milliseconds.

boolean

predefinito:"false"

Disables tooltip interaction for this trigger without disabling its native element.

TooltipHandle<Payload>

A handle to associate the trigger with a tooltip.

Payload

A payload to pass to the tooltip when it is opened.

Ref to the rendered trigger element, a button by default.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipTriggerState>

Composes a native element or a component that forwards attributes, handlers and ref.

CSSProperties | ((state: TooltipTriggerState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

string | ((state: TooltipPortalState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

Portal destination. Defaults to the current theme container, then the document body.

boolean

predefinito:"false"

Whether to keep the portal mounted in the DOM while the popup is hidden.

Ref<HTMLDivElement>

Ref to the portal div.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPortalState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: TooltipPortalState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

"center" | "end" | "start"

predefinito:"center"

How to align the popup relative to the specified side.

number | OffsetFunction

predefinito:"0"

Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment.The function takes a data object parameter with the following properties:

data.anchor: the dimensions of the anchor element with properties width and height.
data.positioner: the dimensions of the positioner element with properties width and height.
data.side: which side of the anchor element the positioner is aligned against.
data.align: how the positioner is aligned relative to the specified side.

An element to position the popup against. By default, the popup will be positioned against the trigger.

number

predefinito:"5"

Minimum distance to maintain between the arrow and the edges of the popup.Use it to prevent the arrow element from hanging out of the rounded corners of a popup.

string | ((state: TooltipPositionerState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

CollisionAvoidance

Determines how to handle collisions when positioning the popup.side controls overflow on the preferred placement axis (top/bottom or left/right):

'flip': keep the requested side when it fits; otherwise try the opposite side (top and bottom, or left and right).
'shift': never change side; keep the requested side and move the popup within the clipping boundary so it stays visible.
'none': do not correct side-axis overflow.

align controls overflow on the alignment axis (start/center/end):

'flip': keep side, but swap start and end when the requested alignment overflows.
'shift': keep side and requested alignment, then nudge the popup along the alignment axis to fit.
'none': do not correct alignment-axis overflow.

fallbackAxisSide controls fallback behavior on the perpendicular axis when the preferred axis cannot fit:

'start': allow perpendicular fallback and try the logical start side first (top before bottom, or left before right in LTR).
'end': allow perpendicular fallback and try the logical end side first (bottom before top, or right before left in LTR).
'none': do not fallback to the perpendicular axis.

When side is 'shift', explicitly setting align only supports 'shift' or 'none'. If align is omitted, it defaults to 'flip'.

Boundary

predefinito:"clipping-ancestors"

An element or a rectangle that delimits the area that the popup is confined to.

Padding

predefinito:"5"

Additional space to maintain from the edge of the collision boundary.

boolean

predefinito:"false"

Whether to disable the popup from tracking any layout shift of its positioning anchor.

"absolute" | "fixed"

predefinito:"absolute"

Determines which CSS position property to use.

Ref<HTMLDivElement>

Ref to the positioning div. Native props, styles and render target this element.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPositionerState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

predefinito:"top"

Preferred physical or logical side of the anchor. Defaults to top.

number | OffsetFunction

predefinito:"0"

Distance from the anchor. Defaults to 0 in compound usage. Accepts a number or positioning function.

boolean

predefinito:"false"

Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.

CSSProperties | ((state: TooltipPositionerState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Content rendered as supplied. Does not create a portal, positioner, title layout or arrow.

CSS class applied to the element, or a function that returns a class based on the component’s state.

Maximum popup width. Defaults to 300 pixels and is capped by the space available beside the anchor.

Ref to the popup div. Native props, styles and render target this element.

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

Style applied to the element, or a function that returns a style object based on the component’s state.

Enables the optional Twenty exit transition.

ReactNode

Optional title content, displayed with medium weight. Omit it for a description-only tooltip.

ReactNode

Optional secondary content. Preserves line breaks and wraps long text.

Ref<HTMLDivElement>

Ref to the body div. Native props, styles and render target this element.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>

Composes the body root through an element or render callback while preserving its layout and content.

ReactNode

Optional decorative node before the title. Omitted when the title is empty.

string | ((state: TooltipArrowState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

Ref<HTMLDivElement>

Ref to the arrow div. Compose inside Popup.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipArrowState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: TooltipArrowState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

ReactNode

The content to render inside the transition container.

string | ((state: TooltipViewportState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

Ref<HTMLDivElement>

Ref to the content-transition div. Useful when several triggers share changing content.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipViewportState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: TooltipViewportState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

ReactNode

Tooltips sharing delay, closeDelay and timeout configuration. Provider renders no DOM node.

number

How long to wait before closing a tooltip. Specified in milliseconds.

number

How long to wait before opening the tooltip on hover. Specified in milliseconds.

number

predefinito:"400"

Another tooltip will open instantly if the previous tooltip is closed within this timeout. Specified in milliseconds.

Sviluppatori

App

API

Auto-ospitazione

Contribuire

Libreria UI

Panoramica

Utilizzo

Stato controllato

Contenuto avanzato e composizione

Migrazione

Controlli disabilitati

Posizionamento e testo in eccesso

Props

Tooltip.Root

Tooltip.Trigger

Tooltip.Portal

Tooltip.Positioner

Tooltip.Body

Tooltip.Arrow

Tooltip.Viewport

Tooltip.Provider

​Panoramica

​Utilizzo

​Stato controllato

​Contenuto avanzato e composizione

​Migrazione

​Controlli disabilitati

​Posizionamento e testo in eccesso

​Props

​Tooltip.Root

​Tooltip.Trigger

​Tooltip.Portal

​Tooltip.Positioner

​Tooltip.Popup

​Tooltip.Body

​Tooltip.Arrow

​Tooltip.Viewport

​Tooltip.Provider

Panoramica

Utilizzo

Stato controllato

Contenuto avanzato e composizione

Migrazione

Controlli disabilitati

Posizionamento e testo in eccesso

Props

Tooltip.Root

Tooltip.Trigger

Tooltip.Portal

Tooltip.Positioner

Tooltip.Popup

Tooltip.Body

Tooltip.Arrow

Tooltip.Viewport

Tooltip.Provider