Información sobre herramientas

Resumen

Usa Tooltip para una explicación breve de un control o texto truncado. Mantén visible la información esencial, asigna a los controles un nombre accesible y usa Popover cuando el contenido contenga enlaces, botones u otros controles.

”Uso”

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>
);

El componente de conveniencia acepta un elemento activador como children. Los elementos nativos reciben directamente los atributos del activador, los controladores de eventos y la ref. Los componentes de activador personalizados deben reenviar todos ellos. Un elemento contenedor también funciona con un componente que no reenvía cada prop del activador. Al pasar el cursor se abre el tooltip después de delay milisegundos, cuyo valor predeterminado es 600. El foco del teclado lo abre inmediatamente. closeDelay tiene como valor predeterminado 0; al pasar el cursor sobre el emergente, permanece abierto a menos que se establezca disableHoverablePopup. Escape lo descarta.

Estado controlado

Use open y onOpenChange juntos cuando la aplicación controla la visibilidad. Use defaultOpen solo para establecer la visibilidad inicial de un tooltip no controlado.

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>
  );
};

Contenido enriquecido y composición

La forma abreviada acepta description y startIcon junto con content. El contenido de nodo personalizado se representa tal como se proporciona, a menos que una descripción o un icono solicite el diseño de título.

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>
);

El uso compuesto expone cada parte instalada de Base UI y el diseño opcional de Tooltip.Body. Ensamble explícitamente el portal, el posicionamiento, el emergente y la flecha opcional. Popup procesa sus elementos secundarios tal como se proporcionan; Body ofrece el mismo diseño de título, descripción e icono decorativo que la forma abreviada.

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	Destino de elemento nativo, prop y ref
`Root`	Coordinación del estado y la carga útil. Sin nodo DOM, props nativas ni ref de DOM. `actionsRef` expone `close` y `unmount`.
`Proveedor`	`delay`, `closeDelay` y `timeout` compartidos. Sin nodo DOM ni ref de DOM.
`Disparador`	Un botón de forma predeterminada. Las props nativas, los controladores, `render` y la ref se dirigen al elemento activador.
`Portal`	El div del portal. De forma predeterminada usa el contenedor del tema y, después, el cuerpo del documento.
`Positioner`	El div de posicionamiento. Gestiona el ancla, el lado físico/lógico, los desplazamientos, la gestión de colisiones, el posicionamiento fijo y el relleno de la flecha.
`Popup`	El div emergente. Gestiona el contenido, las props nativas, los estilos, `render` y la ref.
`Body`	El div opcional del cuerpo dentro de Popup o Viewport. Las props nativas, los estilos, `render` y la ref apuntan a su raíz.
`Arrow`	El div de flecha dentro de Popup.
`Viewport`	El div opcional para las transiciones entre cargas útiles de activadores.

Tooltip.Body acepta elementos secundarios de título opcionales y nodos description y startIcon. Los títulos usan un grosor medio; las descripciones usan el color secundario del tooltip, conservan los saltos de línea y ajustan el texto largo. Omite los elementos secundarios de título para un tooltip que solo tenga descripción. El icono es decorativo y solo aparece con un título. Body no añade ningún rol de tooltip, estilos de popup, tamaño ni posicionamiento. El contenido arbitrario de Popup sigue siendo compatible. Importa TooltipBodyProps desde twenty-ui/primitives/surfaces al tipar un contenedor. Cada parte de DOM acepta props nativas, refs y composición de render mediante elemento o devolución de llamada. Las props nativas de nivel superior de la forma abreviada, render y la ref se dirigen a Popup. Use triggerProps, positionerProps y portalProps para personalizar los otros destinos; estas anulan los valores predeterminados de la forma abreviada. Los elementos secundarios proporcionan el elemento de representación predeterminado del activador. Ambas formas conservan el estado Root controlado/no controlado y los detalles del evento de devolución de llamada de Base UI, incluidos la cancelación, el motivo, el evento original y el activador activo. Tooltip.createHandle\<TPayload>() conecta activadores desacoplados con cualquiera de las dos formas mediante handle. Los elementos secundarios de Root compuesto o content de la forma abreviada pueden ser una función que reciba la carga útil activa tipada. Tooltip.Handle y el tipo público TooltipHandle exponen el contrato de identificador instalado. Los identificadores admiten open(triggerId) y close() imperativos mientras su Root está montado.

Migración

Reemplace content={<Tooltip.Content description={description} startIcon={icon}>title</Tooltip.Content>} por content={title} description={description} startIcon={icon}. En el uso compuesto, utiliza Tooltip.Body para el diseño compartido de título y descripción, o compón tu propio contenido. Se eliminan Tooltip.Content y TooltipContentProps. Las props de posicionamiento existentes de Popup compuesto se trasladan a Positioner. Envuélvelo en Portal, mueve container y keepMounted a Portal, conserva maxWidth en Popup y reemplaza arrow por un elemento secundario Arrow. Conserva explícitamente el espaciado anterior con sideOffset={10} cuando sea necesario. El posicionador compuesto conserva el sideOffset={0} de Base UI. Ambas formas limitan Popup a 300 píxeles de forma predeterminada.

Controles deshabilitados

Los botones nativos deshabilitados no pueden recibir el foco del teclado. Envuelva uno en un activador enfocable para que los usuarios puedan descubrir por qué la acción no está disponible.

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>
);

Establecer disabled en la forma abreviada o Root suprime el tooltip en sí. disabled del activador suprime la interacción del tooltip de ese activador. Deshabilite el control nativo mediante sus propias props o el elemento de representación de Trigger.

Ubicación y texto desbordado

La forma abreviada usa de forma predeterminada side="top", align="center" y sideOffset={10}. Tanto las descripciones emergentes abreviadas como las compuestas tienen una anchura máxima de 300 píxeles, limitada por el espacio disponible junto al ancla. Pasa maxWidth a la abreviada o a Tooltip.Popup para elegir un máximo diferente, incluidas vistas previas más amplias. Los estilos de ventana emergente nativos siguen estando disponibles para tamaños personalizados. La ubicación se ajusta al espacio disponible. Un tooltip abierto se oculta mientras su ancla se desplaza fuera de la vista, incluso fuera de un contenedor de desplazamiento. Use arrow para una flecha y container para anular el destino del portal del tema; consulte temas. Use OverflowingTextWithTooltip cuando una etiqueta de texto deba mostrar su valor completo solo cuando esté truncada. Sus props existentes text, tooltipContent y tooltipPlace siguen disponibles.

”Props”

La referencia se genera a partir de los tipos de componentes públicos. También se aceptan atributos y controladores de eventos nativos del emergente.

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"

predeterminado:"center"

Alignment relative to the trigger. Defaults to center.

number | OffsetFunction

predeterminado:"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

predeterminado:"5"

Minimum distance from the arrow to the popup edges.

ReactElement<unknown, string | JSXElementConstructor<any>>

requerido

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

predeterminado:"0"

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

boolean

predeterminado:"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

predeterminado:"clipping-ancestors"

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

Padding

predeterminado:"5"

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

Portal destination. Defaults to the current theme container.

ReactNode | PayloadChildRenderFunction<TPayload>

requerido

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

boolean

predeterminado:"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

predeterminado:"600"

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

ReactNode

Optional secondary text below the shorthand title.

boolean

predeterminado:"false"

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

boolean

predeterminado:"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"

predeterminado:"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.

predeterminado:"top"

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

number | OffsetFunction

predeterminado:"10"

Distance from the trigger in pixels. Defaults to 10.

ReactNode

Optional node before the shorthand title.

boolean

predeterminado:"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"

predeterminado:"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

predeterminado:"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

predeterminado:"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"

predeterminado:"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

predeterminado:"0"

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

boolean

predeterminado:"true"

Whether the tooltip should close when this trigger is clicked.

number

predeterminado:"600"

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

boolean

predeterminado:"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

predeterminado:"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"

predeterminado:"center"

How to align the popup relative to the specified side.

number | OffsetFunction

predeterminado:"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

predeterminado:"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

predeterminado:"clipping-ancestors"

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

Padding

predeterminado:"5"

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

boolean

predeterminado:"false"

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

"absolute" | "fixed"

predeterminado:"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.

predeterminado:"top"

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

number | OffsetFunction

predeterminado:"0"

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

boolean

predeterminado:"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

predeterminado:"400"

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

Desarrolladores

Aplicaciones

API

Autoalojamiento

Contribuir

Biblioteca de IU

Resumen

”Uso”

Estado controlado

Contenido enriquecido y composición

Migración

Controles deshabilitados

Ubicación y texto desbordado

”Props”

Tooltip.Root

Tooltip.Trigger

Tooltip.Portal

Tooltip.Positioner

Tooltip.Body

Tooltip.Arrow

Tooltip.Viewport

Tooltip.Provider

​Resumen

​”Uso”

​Estado controlado

​Contenido enriquecido y composición

​Migración

​Controles deshabilitados

​Ubicación y texto desbordado

​”Props”

​Tooltip.Root

​Tooltip.Trigger

​Tooltip.Portal

​Tooltip.Positioner

​Tooltip.Popup

​Tooltip.Body

​Tooltip.Arrow

​Tooltip.Viewport

​Tooltip.Provider

Resumen

”Uso”

Estado controlado

Contenido enriquecido y composición

Migración

Controles deshabilitados

Ubicación y texto desbordado

”Props”

Tooltip.Root

Tooltip.Trigger

Tooltip.Portal

Tooltip.Positioner

Tooltip.Popup

Tooltip.Body

Tooltip.Arrow

Tooltip.Viewport

Tooltip.Provider