Prezentare generală
FolosițiTooltip pentru o explicație scurtă a unui element de control sau a textului trunchiat. Păstrați informațiile esențiale vizibile, oferiți elementelor de control un nume accesibil și folosiți Fereastră contextuală atunci când conținutul conține linkuri, butoane sau alte elemente de control.
Utilizare
children. Elementele native primesc direct atributele declanșatorului, gestionarele de evenimente și referința. Componentele declanșatoare personalizate trebuie să le redirecționeze pe toate. Un element învăluitor funcționează și cu o componentă care nu redirecționează fiecare proprietate a declanșatorului.
Trecerea cursorului deschide tooltipul după delay milisecunde, care are implicit valoarea 600. Focalizarea de la tastatură îl deschide imediat. closeDelay are implicit valoarea 0; trecerea cursorului peste fereastra pop-up o menține deschisă, cu excepția cazului în care este setat disableHoverablePopup. Tasta Escape îl închide.
Stare controlată
Utilizați împreunăopen și onOpenChange când aplicația controlează vizibilitatea. Utilizați defaultOpen numai pentru a seta vizibilitatea inițială a unui tooltip necontrolat.
Conținut îmbogățit și compoziție
Forma prescurtată acceptădescription și startIcon pe lângă content. Conținutul nodului personalizat este redat așa cum este furnizat, cu excepția cazului în care o descriere sau o pictogramă solicită aspectul titlului.
Tooltip.Body. Asamblați explicit portalul, poziționarea, fereastra pop-up și săgeata opțională. Popup redă elementele sale copil așa cum sunt furnizate; Body oferă aceeași structură de titlu, descriere și pictogramă decorativă ca forma prescurtată.
Tooltip.Body acceptă elemente copil title opționale, noduri description și startIcon. Titlurile folosesc grosime medie; descrierile folosesc culoarea secundară a tooltipului, păstrează întreruperile de linie și încadrează textul lung. Omiteți elementele copil title pentru un tooltip care conține doar o descriere. Pictograma este decorativă și apare doar împreună cu un titlu. Body nu adaugă niciun rol de tooltip, stilizare de popup, dimensionare sau poziționare. Conținutul Popup arbitrar rămâne acceptat. Importați TooltipBodyProps din twenty-ui/primitives/surfaces când tipizați un wrapper.
Fiecare parte DOM acceptă proprietăți native, referințe și compoziție render cu element sau funcție de apel invers. Proprietățile native de nivel superior ale formei prescurtate, render și referința vizează Popup. Utilizați triggerProps, positionerProps și portalProps pentru a personaliza celelalte ținte; acestea suprascriu valorile implicite ale formei prescurtate. Elementele copil furnizează elementul implicit de redare a declanșatorului. Ambele forme păstrează starea Root controlată/necontrolată și detaliile evenimentelor de apel invers Base UI, inclusiv anularea, motivul, evenimentul original și declanșatorul activ.
Tooltip.createHandle\<TPayload>() conectează declanșatoarele detașate la oricare dintre forme prin handle. Elementele copil ale Root compus sau content al formei prescurtate pot fi o funcție care primește încărcătura utilă activă tipizată. Tooltip.Handle și tipul public TooltipHandle expun contractul handle instalat. Handle-urile acceptă apelurile imperative open(triggerId) și close() cât timp Root-ul lor este montat.
Migrare
Înlocuițicontent={<Tooltip.Content description={description} startIcon={icon}>title</Tooltip.Content>} cu content={title} description={description} startIcon={icon}. În utilizarea compusă, folosiți Tooltip.Body pentru aspectul comun al titlului și al descrierii sau compuneți propriul conținut. Tooltip.Content și TooltipContentProps sunt eliminate.
Proprietățile existente de poziționare Popup compus se mută la Positioner. Înfășurați-l în Portal, mutați container și keepMounted în Portal, păstrați maxWidth în Popup și înlocuiți arrow cu un copil Arrow. Păstrați explicit spațierea anterioară cu sideOffset={10} atunci când este necesar. Compound Positioner păstrează sideOffset={0} din Base UI. Ambele forme limitează implicit Popup la 300 de pixeli.
Comenzi dezactivate
Butoanele native dezactivate nu pot primi focalizare de la tastatură. Înfășurați unul într-un declanșator focalizabil, astfel încât utilizatorii să poată afla de ce acțiunea nu este disponibilă.disabled pe forma prescurtată sau pe Root suprimă tooltipul propriu-zis. disabled al declanșatorului suprimă interacțiunea cu tooltipul acelui declanșator. Dezactivați controlul nativ prin propriile sale proprietăți sau prin elementul de redare al Trigger.
Plasare și text care depășește spațiul disponibil
Forma prescurtată are implicitside="top", align="center" și sideOffset={10}. Atât descrierile scurte, cât și cele complexe au o lățime maximă de 300 de pixeli, limitată de spațiul disponibil de lângă ancoră. Transmiteți maxWidth către descrierea scurtă sau către Tooltip.Popup pentru a alege o altă valoare maximă, inclusiv previzualizări mai late. Stilurile native de ferestre pop-up rămân disponibile pentru dimensionare personalizată. Plasarea se ajustează la spațiul disponibil. Un tooltip deschis se ascunde când ancora sa este derulată în afara vizualizării, inclusiv în afara unui container de derulare. Utilizați arrow pentru o săgeată și container pentru a suprascrie destinația portalului temei; consultați tematizarea.
Utilizați OverflowingTextWithTooltip când o etichetă text trebuie să-și afișeze valoarea completă numai atunci când este trunchiată. Proprietățile sale existente text, tooltipContent și tooltipPlace rămân disponibile.
Proprietăți
Referința este generată din tipurile de componente publice. Sunt acceptate și atributele native ale ferestrei pop-up, precum și gestionarele de evenimente.A ref to imperative actions.
unmount: Ends the closing phase of the tooltip after an externally controlled closing animation finishes. CallpreventUnmountOnClose()inonOpenChangefirst, otherwise the tooltip completes closing on its own. Whether it leaves the DOM is decided bykeepMountedon the portal.close: Closes the tooltip imperatively when called.
Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null
An explicit positioning anchor for the popup.
A single trigger element. Custom components must forward their ref, native attributes, and event handlers.
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 (topandbottom, orleftandright).'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 swapstartandendwhen 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 (topbeforebottom, orleftbeforerightin LTR).'end': allow perpendicular fallback and try the logical end side first (bottombeforetop, orrightbeforeleftin LTR).'none': do not fallback to the perpendicular axis.
side is 'shift', explicitly setting align only supports 'shift' or 'none'.
If align is omitted, it defaults to 'flip'.An element or a rectangle that delimits the area that the popup is confined to.
Portal destination. Defaults to the current theme container.
Supplementary content, or a function receiving the active trigger payload. Strings and numbers use the shorthand title layout.
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.Whether to disable the popup from tracking any layout shift of its positioning anchor.
Maximum popup width. Defaults to 300 pixels and is capped by the space available beside the anchor.
Receives the requested open state and unchanged Base UI event details, including reason, event, trigger and cancel().
Event handler called after any animations complete when the tooltip is opened or closed.
Full Portal props, including native props, ref and render. Overrides shorthand portal defaults.
Full Positioner props, including native props, ref and render. Overrides shorthand placement defaults.
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.Preferred side of the trigger. Defaults to top and may change to avoid collisions.
Whether to maintain the popup in the viewport after
the anchor element was scrolled out of view.
Inline styles for the popup.
Determines which axis the tooltip should track the cursor on.
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).Full Trigger props, including native props, ref, render and payload. Overrides the shorthand trigger defaults.
Tooltip.Root
A ref to imperative actions.
unmount: Ends the closing phase of the tooltip after an externally controlled closing animation finishes. CallpreventUnmountOnClose()inonOpenChangefirst, otherwise the tooltip completes closing on its own. Whether it leaves the DOM is decided bykeepMountedon the portal.close: Closes the tooltip imperatively when called.
Parts or a render function receiving the active trigger payload. Root renders no DOM node.
Whether the tooltip is initially open.To render a controlled tooltip, use the
open prop instead.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.Receives the requested open state and unchanged Base UI event details, including reason, event, trigger and cancel().
Event handler called after any animations complete when the tooltip is opened or closed.
Determines which axis the tooltip should track the cursor on.
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).Tooltip.Trigger
CSS class applied to the element, or a function that
returns a class based on the component’s state.
How long to wait before opening the tooltip on hover. Specified in milliseconds.
Disables tooltip interaction for this trigger without disabling its native element.
((((instance: HTMLButtonElement | null) => void | (() => VoidOrUndefinedOnly)) | RefObject<HTMLButtonElement | null>) & (((instance: HTMLElement | null) => void | (() => VoidOrUndefinedOnly)) | RefObject<...>)) | null
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.
Style applied to the element, or a function that
returns a style object based on the component’s state.
Tooltip.Portal
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.
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.Style applied to the element, or a function that
returns a style object based on the component’s state.
Tooltip.Positioner
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 propertieswidthandheight.data.positioner: the dimensions of the positioner element with propertieswidthandheight.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.
Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null
An element to position the popup against.
By default, the popup will be positioned against the trigger.
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.
CSS class applied to the element, or a function that
returns a class based on the component’s state.
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 (topandbottom, orleftandright).'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 swapstartandendwhen 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 (topbeforebottom, orleftbeforerightin LTR).'end': allow perpendicular fallback and try the logical end side first (bottombeforetop, orrightbeforeleftin LTR).'none': do not fallback to the perpendicular axis.
side is 'shift', explicitly setting align only supports 'shift' or 'none'.
If align is omitted, it defaults to 'flip'.An element or a rectangle that delimits the area that the popup is confined to.
Whether to disable the popup from tracking any layout shift of its positioning anchor.
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.Preferred physical or logical side of the anchor. Defaults to top.
Distance from the anchor. Defaults to 0 in compound usage. Accepts a number or positioning function.
Whether to maintain the popup in the viewport after
the anchor element was scrolled out of view.
Style applied to the element, or a function that
returns a style object based on the component’s state.
Tooltip.Popup
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.
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.Style applied to the element, or a function that
returns a style object based on the component’s state.
Tooltip.Body
Optional title content, displayed with medium weight. Omit it for a description-only tooltip.
Composes the body root through an element or render callback while preserving its layout and content.
Tooltip.Arrow
CSS class applied to the element, or a function that
returns a class based on the component’s state.
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.Style applied to the element, or a function that
returns a style object based on the component’s state.
Tooltip.Viewport
CSS class applied to the element, or a function that
returns a class based on the component’s state.
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.Style applied to the element, or a function that
returns a style object based on the component’s state.
Tooltip.Provider
Tooltips sharing delay, closeDelay and timeout configuration. Provider renders no DOM node.