نظرة عامة
استخدمTooltip لشرح مختصر لعنصر تحكم أو لنص مقتطع. أبقِ المعلومات الأساسية مرئية، وامنح عناصر التحكم اسمًا يمكن الوصول إليه، واستخدم نافذة منبثقة عندما يحتوي المحتوى على روابط أو أزرار أو عناصر تحكم أخرى.
استخدام
children. تتلقى العناصر الأصلية سمات المشغّل ومعالجات الأحداث والمرجع مباشرةً. يجب أن تمرّر مكوّنات المشغّل المخصصة جميعها. يعمل عنصر الغلاف أيضًا مع مكوّن لا يمرّر كل خاصية للمشغّل.
يفتح التمرير فوق العنصر تلميح الأدوات بعد delay مللي ثانية، وقيمته الافتراضية هي 600. يفتحه التركيز عبر لوحة المفاتيح فورًا. القيمة الافتراضية لـ closeDelay هي 0؛ ويبقي التمرير فوق النافذة المنبثقة مفتوحة ما لم يتم تعيين disableHoverablePopup. يؤدي مفتاح Escape إلى إغلاقه.
الحالة المتحكَّم بها
استخدمopen وonOpenChange معًا عندما يمتلك التطبيق التحكم في مستوى الظهور. استخدم defaultOpen فقط لتعيين مستوى الظهور الابتدائي لتلميح أدوات غير متحكَّم به.
المحتوى الغني والتركيب
تقبل الصيغة المختصرةdescription وstartIcon إلى جانب content. يُعرض محتوى العقدة المخصصة كما هو مقدَّم، ما لم يطلب الوصف أو الرمز تخطيط العنوان.
Tooltip.Body. ركّب البوابة والتموضع والنافذة المنبثقة والسهم الاختياري صراحةً. يعرض Popup عناصره التابعة كما تم توفيرها؛ ويوفر Body تخطيط العنوان والوصف والأيقونة الزخرفية نفسه كما في الصيغة المختصرة.
يقبل
Tooltip.Body عناصر فرعية اختيارية للعنوان، وعُقدتي description وstartIcon. تستخدم العناوين وزناً متوسطاً؛ وتستخدم الأوصاف لون التلميح الثانوي، وتحافظ على فواصل الأسطر وتلف النص الطويل. احذف العناصر الفرعية للعنوان للحصول على تلميح يحتوي على وصف فقط. الأيقونة زخرفية ولا تظهر إلا مع عنوان. لا يضيف Body دور Tooltip أو تنسيق Popup أو التحجيم أو التموضع. يظل محتوى Popup الاعتباطي مدعوماً. استورد TooltipBodyProps من twenty-ui/primitives/surfaces عند كتابة غلاف.
يقبل كل جزء من DOM الخصائص الأصلية والمراجع وتركيب render باستخدام عنصر أو دالة رد نداء. تستهدف الخصائص الأصلية ذات المستوى الأعلى للصيغة المختصرة وrender والمرجع Popup. استخدم triggerProps وpositionerProps وportalProps لتخصيص الأهداف الأخرى؛ إذ تتجاوز هذه القيم الافتراضية للصيغة المختصرة. توفر العناصر التابعة عنصر العرض الافتراضي للمشغّل. يحافظ الشكلان على حالة Root المتحكَّم بها/غير المتحكَّم بها وتفاصيل حدث دالة رد النداء في Base UI، بما في ذلك الإلغاء والسبب والحدث الأصلي والمشغّل النشط.
يربط Tooltip.createHandle\<TPayload>() المشغّلات المنفصلة بأي من الشكلين عبر handle. يمكن أن تكون العناصر التابعة لـ Root المركب أو content الخاص بالصيغة المختصرة دالة تستقبل الحمولة النشطة ذات النوع المحدد. يكشف Tooltip.Handle والنوع العام TooltipHandle عن عقد المقبض المثبّت. تدعم المقابض open(triggerId) وclose() الإلزاميين أثناء تثبيت Root الخاص بها.
الترحيل
استبدلcontent={<Tooltip.Content description={description} startIcon={icon}>title</Tooltip.Content>} بـ content={title} description={description} startIcon={icon}. في الاستخدام المركب، استخدم Tooltip.Body لتخطيط العنوان والوصف المشترك، أو أنشئ محتواك الخاص. تمت إزالة Tooltip.Content وTooltipContentProps.
تُنقل خصائص تموضع Popup المركب الحالية إلى Positioner. ضعه داخل Portal، وانقل container وkeepMounted إلى Portal، وأبقِ maxWidth على Popup، واستبدل arrow بعنصر Arrow فرعي. حافظ على التباعد السابق صراحةً باستخدام sideOffset={10} عند الحاجة. يحتفظ Positioner المركب بقيمة Base UI وهي sideOffset={0}. يحد كلا الشكلين Popup عند 300 بكسل افتراضيًا.
عناصر التحكم المعطلة
لا يمكن للأزرار الأصلية المعطلة تلقي التركيز عبر لوحة المفاتيح. غلّف أحدها بمشغّل قابل للتركيز حتى يتمكن المستخدمون من معرفة سبب عدم توفر الإجراء.disabled على الصيغة المختصرة أو Root إلى تعطيل تلميح الأدوات نفسه. يؤدي disabled الخاص بالمشغّل إلى تعطيل تفاعل تلميح الأدوات لذلك المشغّل. عطّل عنصر التحكم الأصلي من خلال خصائصه الخاصة أو عنصر العرض الخاص بـ Trigger.
الموضع والنص المتجاوز
تكون القيم الافتراضية للاختصار هيside="top" وalign="center" وsideOffset={10}. يبلغ الحد الأقصى لعرض كلٍّ من تلميحات الأدوات المختصرة والمركبة 300 بكسل، ويُقيَّد بالمساحة المتاحة بجانب المرساة. مرّر maxWidth إلى المختصر أو Tooltip.Popup لاختيار حد أقصى مختلف، بما في ذلك المعاينات الأعرض. تظل أنماط النوافذ المنبثقة الأصلية متاحة لتحديد حجم مخصص. يتكيف الموضع مع المساحة المتاحة. يُخفى تلميح الأدوات المفتوح عند تمرير نقطة إرسائه خارج نطاق العرض، بما في ذلك خارج حاوية تمرير. استخدم arrow لإضافة سهم وcontainer لتجاوز وجهة البوابة الخاصة بالنسق؛ راجع التنسيق.
استخدم OverflowingTextWithTooltip عندما ينبغي لتسمية نصية إظهار قيمتها الكاملة فقط عند اقتطاعها. تظل خصائص text وtooltipContent وtooltipPlace الحالية متاحة.
الخصائص
يُنشأ المرجع من أنواع المكوّنات العامة. تُقبل أيضًا سمات النافذة المنبثقة الأصلية ومعالجات الأحداث.RefObject<TooltipRootActions | null>
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.
"center" | "end" | "start"
افتراضي:"center"
Alignment relative to the trigger. Defaults to center.
number | OffsetFunction
افتراضي:"0"
Offset along the alignment axis in pixels.
Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null
An explicit positioning anchor for the popup.
boolean
Displays an arrow pointing to the trigger. Defaults to false.
number
افتراضي:"5"
Minimum distance from the arrow to the popup edges.
ReactElement<unknown, string | JSXElementConstructor<any>>
مطلوب
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
افتراضي:"0"
Delay in milliseconds before closing after hover ends. Defaults to 0.
boolean
افتراضي:"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 (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'.Boundary
افتراضي:"clipping-ancestors"
An element or a rectangle that delimits the area that the popup is confined to.
Padding
افتراضي:"5"
Additional space to maintain from the edge of the collision boundary.
HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null
Portal destination. Defaults to the current theme container.
ReactNode | PayloadChildRenderFunction<TPayload>
مطلوب
Supplementary content, or a function receiving the active trigger payload. Strings and numbers use the shorthand title layout.
boolean
افتراضي:"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
افتراضي:"600"
Delay in milliseconds before opening on hover. Defaults to 600.
ReactNode
Optional secondary text below the shorthand title.
boolean
افتراضي:"false"
Whether to disable the popup from tracking any layout shift of its positioning anchor.
boolean
افتراضي:"false"
Prevents the tooltip from opening.
boolean
افتراضي:"false"
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"
افتراضي:"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."bottom" | "inline-end" | "inline-start" | "left" | "right" | "top"
افتراضي:"top"
Preferred side of the trigger. Defaults to top and may change to avoid collisions.
number | OffsetFunction
افتراضي:"10"
Distance from the trigger in pixels. Defaults to 10.
ReactNode
Optional node before the shorthand title.
boolean
افتراضي:"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"
افتراضي:"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.
Tooltip.Root
RefObject<TooltipRootActions | null>
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.
ReactNode | PayloadChildRenderFunction<Payload>
Parts or a render function receiving the active trigger payload. Root renders no DOM node.
boolean
افتراضي:"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
افتراضي:"false"
Whether the tooltip is disabled.
boolean
افتراضي:"false"
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"
افتراضي:"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).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
افتراضي:"0"
How long to wait before closing the tooltip. Specified in milliseconds.
boolean
افتراضي:"true"
Whether the tooltip should close when this trigger is clicked.
number
افتراضي:"600"
How long to wait before opening the tooltip on hover. Specified in milliseconds.
boolean
افتراضي:"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.
((((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.
CSSProperties | ((state: TooltipTriggerState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.
Tooltip.Portal
string | ((state: TooltipPortalState) => string | undefined)
CSS class applied to the element, or a function that
returns a class based on the component’s state.
HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null
Portal destination. Defaults to the current theme container, then the document body.
boolean
افتراضي:"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.
Tooltip.Positioner
"center" | "end" | "start"
افتراضي:"center"
How to align the popup relative to the specified side.
number | OffsetFunction
افتراضي:"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 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.
number
افتراضي:"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 (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'.Boundary
افتراضي:"clipping-ancestors"
An element or a rectangle that delimits the area that the popup is confined to.
Padding
افتراضي:"5"
Additional space to maintain from the edge of the collision boundary.
boolean
افتراضي:"false"
Whether to disable the popup from tracking any layout shift of its positioning anchor.
"absolute" | "fixed"
افتراضي:"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."bottom" | "inline-end" | "inline-start" | "left" | "right" | "top"
افتراضي:"top"
Preferred physical or logical side of the anchor. Defaults to top.
number | OffsetFunction
افتراضي:"0"
Distance from the anchor. Defaults to 0 in compound usage. Accepts a number or positioning function.
boolean
افتراضي:"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.
Tooltip.Popup
ReactNode
Content rendered as supplied. Does not create a portal, positioner, title layout or arrow.
string | ((state: TooltipPopupState) => string | undefined)
CSS class applied to the element, or a function that
returns a class based on the component’s state.
MaxWidth<string | number>
Maximum popup width. Defaults to 300 pixels and is capped by the space available beside the anchor.
Ref<HTMLDivElement>
Ref to the popup div. Native props, styles and render target this 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.CSSProperties | ((state: TooltipPopupState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.
boolean
افتراضي:"false"
Enables the optional Twenty exit transition.
Tooltip.Body
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.
Tooltip.Arrow
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.
Tooltip.Viewport
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.
Tooltip.Provider
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
افتراضي:"400"
Another tooltip will open instantly if the previous tooltip
is closed within this timeout. Specified in milliseconds.