diff --git a/docs/data/material/components/autocomplete/autocomplete.md b/docs/data/material/components/autocomplete/autocomplete.md
index 77760edefb0924..18144c8d8a168e 100644
--- a/docs/data/material/components/autocomplete/autocomplete.md
+++ b/docs/data/material/components/autocomplete/autocomplete.md
@@ -1,7 +1,7 @@
---
productId: material-ui
title: React Autocomplete component
-components: TextField, Popper, Autocomplete
+components: Autocomplete, TextField, Popper, FloatingPopup
githubLabel: 'scope: autocomplete'
waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
githubSource: packages/mui-material/src/Autocomplete
diff --git a/docs/data/material/components/tooltips/tooltips.md b/docs/data/material/components/tooltips/tooltips.md
index 8ae7dc7bcd488c..be6d5972dfba1b 100644
--- a/docs/data/material/components/tooltips/tooltips.md
+++ b/docs/data/material/components/tooltips/tooltips.md
@@ -1,7 +1,7 @@
---
productId: material-ui
title: React Tooltip component
-components: Tooltip
+components: Tooltip, FloatingPopup
githubLabel: 'scope: tooltip'
materialDesign: https://m2.material.io/components/tooltips
waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/
diff --git a/docs/data/material/pagesApi.js b/docs/data/material/pagesApi.js
index ee76034af9e54a..3b69f24d66e008 100644
--- a/docs/data/material/pagesApi.js
+++ b/docs/data/material/pagesApi.js
@@ -41,6 +41,7 @@ export default [
{ pathname: '/material-ui/api/fab' },
{ pathname: '/material-ui/api/fade' },
{ pathname: '/material-ui/api/filled-input' },
+ { pathname: '/material-ui/api/floating-popup' },
{ pathname: '/material-ui/api/form-control' },
{ pathname: '/material-ui/api/form-control-label' },
{ pathname: '/material-ui/api/form-group' },
diff --git a/docs/package.json b/docs/package.json
index d31c97b566a3a7..d558b493d3ada0 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -25,6 +25,7 @@
"@emotion/react": "catalog:docs",
"@emotion/server": "catalog:docs",
"@emotion/styled": "catalog:docs",
+ "@floating-ui/react-dom": "^2.1.6",
"@fortawesome/fontawesome-svg-core": "^6.7.2",
"@fortawesome/free-solid-svg-icons": "^6.7.2",
"@fortawesome/react-fontawesome": "^0.2.6",
diff --git a/docs/pages/experiments/material-ui/floating-autocomplete.tsx b/docs/pages/experiments/material-ui/floating-autocomplete.tsx
new file mode 100644
index 00000000000000..222e29a266174c
--- /dev/null
+++ b/docs/pages/experiments/material-ui/floating-autocomplete.tsx
@@ -0,0 +1,215 @@
+import * as React from 'react';
+import CssBaseline from '@mui/material/CssBaseline';
+import TextField from '@mui/material/TextField';
+import Autocomplete from '@mui/material/Autocomplete';
+import FloatingPopup from '@mui/material/FloatingPopup';
+
+const TOP_FILMS = [
+ { label: 'The Shawshank Redemption', year: 1994 },
+ { label: 'The Godfather', year: 1972 },
+ { label: 'The Dark Knight', year: 2008 },
+ { label: "Schindler's List", year: 1993 },
+ { label: 'Pulp Fiction', year: 1994 },
+ { label: 'The Lord of the Rings: The Return of the King', year: 2003 },
+ { label: 'Forrest Gump', year: 1994 },
+ { label: 'Inception', year: 2010 },
+ { label: 'Fight Club', year: 1999 },
+ { label: 'The Matrix', year: 1999 },
+ { label: 'Goodfellas', year: 1990 },
+ { label: 'Star Wars: Episode V', year: 1980 },
+ { label: 'City of God', year: 2002 },
+ { label: 'Se7en', year: 1995 },
+ { label: 'The Silence of the Lambs', year: 1991 },
+ { label: "It's a Wonderful Life", year: 1946 },
+ { label: 'Life Is Beautiful', year: 1997 },
+ { label: 'The Usual Suspects', year: 1995 },
+ { label: 'Spirited Away', year: 2001 },
+ { label: 'Saving Private Ryan', year: 1998 },
+];
+
+function BasicDemo() {
+ return (
+
+ Basic
+
+
+
Default (Popper.js)
+
+
+
FloatingPopup
+
+
+ );
+}
+
+function DisablePortalDemo() {
+ return (
+
+ );
+}
+
+function ScrollContainerDemo() {
+ return (
+
+ Inside scroll container
+
+ Dropdown flips when there is not enough space below.
+
+
+
+ );
+}
+
+function MultipleDemo() {
+ return (
+
+ Multiple values
+
+ );
+}
+
+function GroupedDemo() {
+ const sorted = [...TOP_FILMS].sort((a, b) => {
+ const decadeA = Math.floor(a.year / 10) * 10;
+ const decadeB = Math.floor(b.year / 10) * 10;
+ return decadeB - decadeA || a.label.localeCompare(b.label);
+ });
+
+ return (
+
+ Grouped
+ `${Math.floor(option.year / 10) * 10}s`}
+ sx={{ width: 300 }}
+ slots={{ popper: FloatingPopup }}
+ renderInput={(params) =>
+ );
+}
+
+function FreeSoloDemo() {
+ return (
+
+ Free solo
+ option.label)}
+ sx={{ width: 300 }}
+ slots={{ popper: FloatingPopup }}
+ renderInput={(params) =>
+ );
+}
+
+function CSSVariablesDemo() {
+ return (
+
+ CSS variables (--anchor-width)
+
+ The dropdown uses var(--anchor-width) to match the input width. Autocomplete
+ already passes style.width via additionalProps, but the CSS
+ variable is also available.
+
+
+ );
+}
+
+function KeepMountedDemo() {
+ return (
+
+ keepMounted (via slotProps)
+
+ The dropdown stays in the DOM when closed (inspect to verify).
+
+
+ );
+}
+
+export default function MaterialUIFloatingAutocomplete() {
+ return (
+
+
+
FloatingPopup + Autocomplete
+
+ {'
+
+
+
+
+ );
+}
diff --git a/docs/pages/experiments/material-ui/floating-tooltip.tsx b/docs/pages/experiments/material-ui/floating-tooltip.tsx
new file mode 100644
index 00000000000000..c701bd75ce7280
--- /dev/null
+++ b/docs/pages/experiments/material-ui/floating-tooltip.tsx
@@ -0,0 +1,278 @@
+import * as React from 'react';
+import CssBaseline from '@mui/material/CssBaseline';
+import Tooltip from '@mui/material/Tooltip';
+import Button from '@mui/material/Button';
+import FloatingPopup from '@mui/material/FloatingPopup';
+import { offset, flip, shift, autoPlacement } from '@floating-ui/react-dom';
+import type { Placement } from '@floating-ui/react-dom';
+
+const PLACEMENTS: Placement[] = [
+ 'top',
+ 'top-start',
+ 'top-end',
+ 'bottom',
+ 'bottom-start',
+ 'bottom-end',
+ 'left',
+ 'left-start',
+ 'left-end',
+ 'right',
+ 'right-start',
+ 'right-end',
+];
+
+function PlacementDemo() {
+ const [placement, setPlacement] = React.useState('top');
+
+ return (
+
+ Placement
+
+ {PLACEMENTS.map((p) => (
+ setPlacement(p)}
+ style={{ fontWeight: placement === p ? 'bold' : 'normal' }}
+ >
+ {p}
+
+ ))}
+
+
+ Hover me
+
+
+ );
+}
+
+function ArrowDemo() {
+ return (
+
+ Arrow
+
+
+ Arrow
+
+
+ No arrow
+
+
+
+ );
+}
+
+function FollowCursorDemo() {
+ return (
+
+ Follow cursor
+
+
+ Move cursor here
+
+
+
+ );
+}
+
+function OffsetDemo() {
+ const [offsetVal, setOffsetVal] = React.useState(8);
+
+ return (
+
+ );
+}
+
+function AutoPlacementDemo() {
+ const [boundary, setBoundary] = React.useState(null);
+
+ const middleware = React.useMemo(
+ () => [
+ offset(8),
+ autoPlacement({
+ allowedPlacements: ['top', 'bottom'],
+ ...(boundary && { boundary }),
+ }),
+ shift(),
+ ],
+ [boundary],
+ );
+
+ return (
+
+ Auto placement (middleware)
+
+ Uses autoPlacement() middleware. Scroll the button near an edge, then hover.
+
+
+
+
+ Hover after scrolling
+
+
+
+ );
+}
+
+function StrategyDemo() {
+ const [strategy, setStrategy] = React.useState<'absolute' | 'fixed'>('absolute');
+
+ return (
+
+ Strategy
+
+ {(['absolute', 'fixed'] as const).map((s) => (
+ setStrategy(s)}
+ style={{ fontWeight: strategy === s ? 'bold' : 'normal' }}
+ >
+ {s}
+
+ ))}
+
+
+ Hover me
+
+
+ );
+}
+
+function CSSVariablesDemo() {
+ return (
+
+ CSS variables
+
+ FloatingPopup sets --anchor-width, --anchor-height,{' '}
+ --available-width, --available-height on the floating element.
+
+
+
+ Tooltip matches this button width
+
+
+
+ );
+}
+
+function ComparisonDemo() {
+ return (
+
+ Side-by-side: Popper.js vs FloatingPopup
+
+
+
Default (Popper.js)
+
+ Popper.js
+
+
+
+
FloatingPopup
+
+ Floating UI
+
+
+
+ );
+}
+
+export default function MaterialUIFloatingPopup() {
+ return (
+
+
+
FloatingPopup experiment
+
+ {'
+
+
+
+ );
+}
diff --git a/docs/pages/material-ui/api/floating-popup.js b/docs/pages/material-ui/api/floating-popup.js
new file mode 100644
index 00000000000000..e7d4c0529b234e
--- /dev/null
+++ b/docs/pages/material-ui/api/floating-popup.js
@@ -0,0 +1,20 @@
+import * as React from 'react';
+import ApiPage from 'docs/src/modules/components/ApiPage';
+import mapApiPageTranslations from 'docs/src/modules/utils/mapApiPageTranslations';
+import jsonPageContent from './floating-popup.json';
+
+export default function Page(props) {
+ const { descriptions } = props;
+ return useState. Also works: RefObject (resolved lazily via Derivable pattern + useLayoutEffect)."
+ }
+ },
+ "classDescriptions": {}
+}
diff --git a/packages/mui-material/package.json b/packages/mui-material/package.json
index c048e78287d664..a9568d430a1140 100644
--- a/packages/mui-material/package.json
+++ b/packages/mui-material/package.json
@@ -34,6 +34,7 @@
},
"dependencies": {
"@babel/runtime": "^7.29.2",
+ "@floating-ui/react-dom": "^2.1.6",
"@mui/core-downloads-tracker": "workspace:^",
"@mui/system": "workspace:*",
"@mui/types": "workspace:^",
@@ -99,6 +100,7 @@
"./ClickAwayListener": "./src/ClickAwayListener/index.ts",
"./darkScrollbar": "./src/darkScrollbar/index.ts",
"./DefaultPropsProvider": "./src/DefaultPropsProvider/index.ts",
+ "./FloatingPopup": "./src/FloatingPopup/index.ts",
"./generateUtilityClass": "./src/generateUtilityClass/index.ts",
"./generateUtilityClasses": "./src/generateUtilityClasses/index.ts",
"./Grid": "./src/Grid/index.ts",
diff --git a/packages/mui-material/src/Autocomplete/Autocomplete.d.ts b/packages/mui-material/src/Autocomplete/Autocomplete.d.ts
index cf58f50550c5e3..fa0771cfb120d7 100644
--- a/packages/mui-material/src/Autocomplete/Autocomplete.d.ts
+++ b/packages/mui-material/src/Autocomplete/Autocomplete.d.ts
@@ -20,9 +20,13 @@ import useAutocomplete, {
} from '../useAutocomplete';
import { AutocompleteClasses } from './autocompleteClasses';
import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';
+import { FloatingPopupProps } from '../FloatingPopup';
export interface AutocompletePaperSlotPropsOverrides {}
-export interface AutocompletePopperSlotPropsOverrides {}
+export interface AutocompletePopperSlotPropsOverrides extends Pick<
+ FloatingPopupProps,
+ 'middleware' | 'strategy' | 'transform' | 'arrowPadding'
+> {}
export {
AutocompleteChangeDetails,
@@ -145,7 +149,7 @@ export interface AutocompleteSlots {
* The component used to position the popup.
* @default Popper
*/
- popper: React.JSXElementConstructor;
+ popper: React.ElementType;
}
export type AutocompleteSlotsAndSlotProps<
diff --git a/packages/mui-material/src/Autocomplete/Autocomplete.floating.spec.tsx b/packages/mui-material/src/Autocomplete/Autocomplete.floating.spec.tsx
new file mode 100644
index 00000000000000..9bd0389afa5263
--- /dev/null
+++ b/packages/mui-material/src/Autocomplete/Autocomplete.floating.spec.tsx
@@ -0,0 +1,75 @@
+import * as React from 'react';
+import { offset, flip, shift, Middleware } from '@floating-ui/react-dom';
+import Autocomplete from '@mui/material/Autocomplete';
+import TextField from '@mui/material/TextField';
+import FloatingPopup from '@mui/material/FloatingPopup';
+
+// FloatingPopup can be passed as the popper slot
+ ({
+ strategy: 'fixed' as const,
+ middleware: [offset(8)],
+ }),
+ }}
+ renderInput={(params) => ['render']>['user'],
+) {
+ const input = screen.getByRole('combobox');
+ await user.click(input);
+ await flushMicrotasks();
+ return input;
+}
+
+/**
+ * Integration tests for Autocomplete with FloatingPopup as the popper slot.
+ *
+ * FloatingPopup uses async computePosition from floating-ui. Until positioning
+ * completes, the popup has `visibility: hidden` which hides it from the
+ * accessibility tree. Tests that query popup DOM call `await flushMicrotasks()`
+ * after interactions that open the popup.
+ */
+describe(' = {}) {
+ return render(
+ option.group}
+ getOptionLabel={(option) => option.label}
+ slots={{ popper: FloatingPopup }}
+ renderInput={(params) => option.group}
+ getOptionLabel={(option) => option.label}
+ slots={{ popper: FloatingPopup }}
+ renderInput={(params) => option.title}
+ slots={{ popper: FloatingPopup }}
+ renderInput={(params) => option.title}
+ onChange={onChange}
+ slots={{ popper: FloatingPopup }}
+ renderInput={(params) => Hello World ,
+ open: true,
+ };
+
+ beforeAll(() => {
+ rtlTheme = createTheme({
+ direction: 'rtl',
+ });
+ defaultAnchorEl = document.createElement('div');
+ document.body.appendChild(defaultAnchorEl);
+ });
+
+ afterAll(() => {
+ document.body.removeChild(defaultAnchorEl!);
+ });
+
+ describe('rendering', () => {
+ it('should render children when open', () => {
+ render((null);
+
+ return (
+
+
+
+ {({ placement }: FloatingPopupChildrenProps) => {
+ return {placement}
;
+ }}
+
+
+ );
+ }
+ render(
+ {({ TransitionProps }: FloatingPopupChildrenProps) => (
+
+ Hello World
+
+ )}
+ ,
+ );
+
+ expect(screen.getByText('Hello World')).not.to.equal(null);
+ });
+
+ it('should unmount after transition exits', () => {
+ const { setProps } = render(
+
+ {({ TransitionProps }: FloatingPopupChildrenProps) => (
+
+ Hello World
+
+ )}
+ ,
+ );
+
+ expect(screen.getByText('Hello World')).not.to.equal(null);
+
+ setProps({ open: false });
+ clock.tick(0);
+
+ expect(screen.queryByText('Hello World')).to.equal(null);
+ });
+ });
+
+ describe('prop: disablePortal', () => {
+ it('should render inline when disablePortal is true', () => {
+ const { container } = render(();
+ render(
+ content
+ ,
+ );
+ expect(screen.getByText('content')).not.to.equal(null);
+ });
+ });
+
+ describe('prop: anchorEl as function', () => {
+ it('should accept anchorEl as a function', () => {
+ const anchorEl = document.createElement('div');
+ document.body.appendChild(anchorEl);
+
+ render(
+ anchorEl} open>
+ content
+ ,
+ );
+ expect(screen.getByText('content')).not.to.equal(null);
+
+ document.body.removeChild(anchorEl);
+ });
+ });
+
+ describe('children as function', () => {
+ it('should pass placement and isPositioned to children', () => {
+ render(
+
+ {({ placement, isPositioned }: FloatingPopupChildrenProps) => (
+
+ )}
+ ,
+ );
+
+ const child = screen.getByTestId('child');
+ expect(child).to.have.attribute('data-placement', 'top');
+ });
+
+ it('should pass arrowStyles and anchorHidden to children', () => {
+ render(
+
+ {({ arrowStyles, anchorHidden }: FloatingPopupChildrenProps) => (
+
+ )}
+ ,
+ );
+
+ const child = screen.getByTestId('child');
+ expect(child).to.have.attribute('data-arrow-position', 'absolute');
+ expect(child).to.have.attribute('data-anchor-hidden', 'false');
+ });
+ });
+});
diff --git a/packages/mui-material/src/FloatingPopup/FloatingPopup.tsx b/packages/mui-material/src/FloatingPopup/FloatingPopup.tsx
new file mode 100644
index 00000000000000..00e302c69f1778
--- /dev/null
+++ b/packages/mui-material/src/FloatingPopup/FloatingPopup.tsx
@@ -0,0 +1,475 @@
+'use client';
+import * as React from 'react';
+import PropTypes from 'prop-types';
+import {
+ useFloating,
+ autoUpdate,
+ offset,
+ flip,
+ shift,
+ hide,
+ arrow,
+ detectOverflow,
+ Placement,
+ Middleware,
+} from '@floating-ui/react-dom';
+import { useRtl } from '@mui/system/RtlProvider';
+import ownerDocument from '@mui/utils/ownerDocument';
+import useForkRef from '@mui/utils/useForkRef';
+import Portal from '../Portal';
+import {
+ FloatingPopupProps,
+ FloatingPopupChildrenProps,
+ VirtualElement,
+} from './FloatingPopup.types';
+
+// Adapted from BasePopper.tsx flipPlacement() — flips start/end for RTL
+function flipPlacement(placement: Placement, isRtl: boolean): Placement {
+ if (!isRtl) {
+ return placement;
+ }
+
+ switch (placement) {
+ case 'bottom-end':
+ return 'bottom-start';
+ case 'bottom-start':
+ return 'bottom-end';
+ case 'top-end':
+ return 'top-start';
+ case 'top-start':
+ return 'top-end';
+ default:
+ return placement;
+ }
+}
+
+// Adapted from BasePopper.tsx isHTMLElement() — local utility
+function isHTMLElement(element: HTMLElement | VirtualElement): element is HTMLElement {
+ return (element as HTMLElement).nodeType !== undefined;
+}
+
+// Custom middleware that computes anchor dimensions and available space,
+// returning data via middlewareData (React-friendly) instead of imperative DOM mutation.
+const anchorMetrics: Middleware = {
+ name: 'anchorMetrics',
+ async fn(state) {
+ const overflow = await detectOverflow(state);
+ const { rects, placement } = state;
+
+ // Snap anchor dimensions to device pixels (from Base UI pattern)
+ const dpr = window.devicePixelRatio || 1;
+ const { x, y, width, height } = rects.reference;
+ const anchorWidth = (Math.round((x + width) * dpr) - Math.round(x * dpr)) / dpr;
+ const anchorHeight = (Math.round((y + height) * dpr) - Math.round(y * dpr)) / dpr;
+
+ // Compute available space from overflow on the placement side
+ const side = placement.split('-')[0];
+ const availableWidth =
+ rects.floating.width + Math.max(0, -overflow.left) + Math.max(0, -overflow.right);
+ const availableHeight =
+ side === 'top' || side === 'bottom'
+ ? rects.floating.height + Math.max(0, -overflow[side])
+ : rects.floating.height + Math.max(0, -overflow.top) + Math.max(0, -overflow.bottom);
+
+ return {
+ data: { anchorWidth, anchorHeight, availableWidth, availableHeight },
+ };
+ },
+};
+
+function buildDefaultMiddleware(): Middleware[] {
+ return [offset(0), flip(), shift(), anchorMetrics, hide({ strategy: 'referenceHidden' })];
+}
+
+/**
+ * FloatingPopup — opt-in replacement for Popper.js-based positioning.
+ * Uses @floating-ui/react-dom under the hood.
+ *
+ * Designed to be used via `slots={{ popper: FloatingPopup }}` on
+ * Autocomplete and Tooltip.
+ *
+ * Demos:
+ *
+ * - [Autocomplete](https://next.mui.com/material-ui/react-autocomplete/)
+ * - [Tooltip](https://next.mui.com/material-ui/react-tooltip/)
+ *
+ * API:
+ *
+ * - [FloatingPopup API](https://next.mui.com/material-ui/api/floating-popup/)
+ */
+const FloatingPopup = React.forwardRef(
+ function FloatingPopup(inProps, forwardedRef) {
+ const {
+ anchorEl: anchorElProp,
+ open,
+ placement: placementProp = 'bottom',
+ strategy: strategyProp = 'absolute',
+ middleware: middlewareProp,
+ transform: transformProp = true,
+ children,
+ transition = false,
+ arrowRef: arrowRefProp,
+ arrowPadding = 0,
+ disablePortal = false,
+ container: containerProp,
+ keepMounted = false,
+ className,
+ style,
+ id,
+ popperRef: popperRefProp,
+ // Root element override (from slotProps.popper.component via useSlot)
+ // @ts-ignore — injected by useSlot when slotProps.popper.component is provided
+ as: RootComponent = 'div',
+ // Destructure and discard Popper.js / useSlot props to prevent DOM leaks
+ // @ts-ignore — Popper.js compat
+ popperOptions,
+ // @ts-ignore — Popper.js compat
+ modifiers,
+ // @ts-ignore — BasePopper wrapper injects this; we use useRtl() directly
+ direction,
+ // @ts-ignore — MUI internal from useSlot/appendOwnerState
+ ownerState,
+ ...other
+ } = inProps as FloatingPopupProps & Record;
+
+ // Resolve placement — auto* not supported by floating-ui, fall back to 'bottom'
+ const safePlacement: Placement =
+ typeof placementProp === 'string' && placementProp.startsWith('auto')
+ ? 'bottom'
+ : placementProp;
+
+ const hasWarnedAutoPlacement = React.useRef(false);
+ if (process.env.NODE_ENV !== 'production') {
+ if (safePlacement !== placementProp && !hasWarnedAutoPlacement.current) {
+ hasWarnedAutoPlacement.current = true;
+ console.warn(
+ 'FloatingPopup: "auto" placement is not supported. ' +
+ 'Use the autoPlacement() middleware instead. Falling back to "bottom".',
+ );
+ }
+ }
+
+ // RTL — handled internally, no direction prop needed
+ const isRtl = useRtl();
+ const rtlPlacement = flipPlacement(safePlacement, isRtl);
+
+ // Resolve anchorEl (function or element)
+ const resolvedAnchorEl = typeof anchorElProp === 'function' ? anchorElProp() : anchorElProp;
+
+ // Build middleware — arrow() uses Derivable pattern to read RefObject.current lazily
+ const middleware = React.useMemo(() => {
+ const stack = middlewareProp ? [...middlewareProp] : buildDefaultMiddleware();
+ // Always append arrow() when arrowRef is present, even with custom middleware.
+ // The arrow is a parent concern (e.g. Tooltip's ArrowSlot), not a middleware concern —
+ // users passing custom middleware shouldn't need to know about arrow positioning.
+ if (arrowRefProp) {
+ // arrow(() => ...) is a Derivable — evaluated on every positioning computation,
+ // not at middleware creation time. This avoids stale closure when arrowRef is a RefObject
+ // (referentially stable, .current changes after mount without triggering useMemo).
+ stack.push(
+ arrow(() => ({
+ element: ('current' in arrowRefProp ? arrowRefProp.current : arrowRefProp) as Element,
+ padding: arrowPadding,
+ })),
+ );
+ }
+ return stack;
+ }, [middlewareProp, arrowRefProp, arrowPadding]);
+
+ // Core positioning
+ const {
+ refs,
+ floatingStyles,
+ placement: computedPlacement,
+ middlewareData,
+ isPositioned,
+ update,
+ } = useFloating({
+ elements: { reference: resolvedAnchorEl as Element | null },
+ placement: rtlPlacement,
+ strategy: strategyProp,
+ middleware,
+ transform: transformProp,
+ whileElementsMounted: autoUpdate,
+ });
+
+ // Merge forwardedRef with floating-ui's setFloating ref
+ const mergedRef = useForkRef(refs.setFloating, forwardedRef);
+
+ // Imperative handle — exposes .update() for followCursor compat
+ React.useImperativeHandle(popperRefProp, () => ({ update }), [update]);
+
+ // Force recomputation when RefObject.current becomes available (before first paint).
+ // No dep array — RefObject is referentially stable so deps can't track .current changes.
+ // update() is cheap (one computePosition call) and idempotent.
+ React.useLayoutEffect(() => {
+ if (
+ arrowRefProp &&
+ typeof arrowRefProp === 'object' &&
+ 'current' in arrowRefProp &&
+ arrowRefProp.current
+ ) {
+ update();
+ }
+ });
+
+ // Apply arrow styles imperatively to the arrow DOM element (same approach as Popper.js's
+ // arrow modifier, which writes styles directly). This is necessary because the arrow element
+ // is rendered by the parent (e.g. Tooltip's ArrowSlot), not by FloatingPopup's render prop.
+ React.useLayoutEffect(() => {
+ const arrowElement =
+ arrowRefProp && typeof arrowRefProp === 'object' && 'current' in arrowRefProp
+ ? arrowRefProp.current
+ : (arrowRefProp as HTMLElement | null);
+ if (!arrowElement || !middlewareData.arrow) {
+ return;
+ }
+ const { x, y } = middlewareData.arrow;
+ Object.assign(arrowElement.style, {
+ left: x != null ? `${x}px` : '',
+ top: y != null ? `${y}px` : '',
+ position: 'absolute',
+ });
+ }, [arrowRefProp, middlewareData.arrow]);
+
+ // Transition state (same pattern as BasePopper)
+ const [exited, setExited] = React.useState(true);
+ const handleEnter = () => setExited(false);
+ const handleExited = () => setExited(true);
+
+ if (!keepMounted && !open && (!transition || exited)) {
+ return null;
+ }
+
+ const display = !open && keepMounted && (!transition || exited) ? 'none' : undefined;
+ const anchorHidden = Boolean(middlewareData.hide?.referenceHidden);
+ const metrics = middlewareData.anchorMetrics as
+ | {
+ anchorWidth: number;
+ anchorHeight: number;
+ availableWidth: number;
+ availableHeight: number;
+ }
+ | undefined;
+ const arrowStyles: React.CSSProperties = {
+ position: 'absolute',
+ top: middlewareData.arrow?.y,
+ left: middlewareData.arrow?.x,
+ };
+
+ const childrenProps: FloatingPopupChildrenProps = {
+ placement: computedPlacement,
+ ...(transition && {
+ TransitionProps: {
+ in: open,
+ onEnter: handleEnter,
+ onExited: handleExited,
+ },
+ }),
+ arrowStyles,
+ anchorHidden,
+ isPositioned,
+ };
+
+ // Resolve Portal container (isHTMLElement matches BasePopper pattern)
+ const container =
+ containerProp ||
+ (resolvedAnchorEl && isHTMLElement(resolvedAnchorEl as HTMLElement | VirtualElement)
+ ? ownerDocument(resolvedAnchorEl as HTMLElement).body
+ : ownerDocument(null).body);
+
+ return (
+
+
+ {typeof children === 'function' ? children(childrenProps) : children}
+
+
+ );
+ },
+);
+
+FloatingPopup.propTypes /* remove-proptypes */ = {
+ // ┌────────────────────────────── Warning ──────────────────────────────┐
+ // │ These PropTypes are generated from the TypeScript type definitions. │
+ // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
+ // └─────────────────────────────────────────────────────────────────────┘
+ /**
+ * @ignore
+ */
+ anchorEl: PropTypes.oneOfType([
+ (props, propName) => {
+ if (props[propName] == null) {
+ return new Error(`Prop '${propName}' is required but wasn't specified`);
+ }
+ if (typeof props[propName] !== 'object' || props[propName].nodeType !== 1) {
+ return new Error(`Expected prop '${propName}' to be of type Element`);
+ }
+ return null;
+ },
+ PropTypes.func,
+ PropTypes.shape({
+ getBoundingClientRect: PropTypes.func.isRequired,
+ }),
+ ]),
+ /**
+ * @ignore
+ */
+ arrowPadding: PropTypes.number,
+ /**
+ * The arrow element to position. Preferred: pass the element from `useState`.
+ * Also works: `RefObject` (resolved lazily via Derivable pattern + useLayoutEffect).
+ */
+ arrowRef: PropTypes.oneOfType([
+ (props, propName) => {
+ if (props[propName] == null) {
+ return new Error(`Prop '${propName}' is required but wasn't specified`);
+ }
+ if (typeof props[propName] !== 'object' || props[propName].nodeType !== 1) {
+ return new Error(`Expected prop '${propName}' to be of type Element`);
+ }
+ return null;
+ },
+ PropTypes.shape({
+ current: (props, propName) => {
+ if (props[propName] == null) {
+ return null;
+ }
+ if (typeof props[propName] !== 'object' || props[propName].nodeType !== 1) {
+ return new Error(`Expected prop '${propName}' to be of type Element`);
+ }
+ return null;
+ },
+ }),
+ ]),
+ /**
+ * @ignore
+ */
+ children: PropTypes.oneOfType([
+ PropTypes.element,
+ PropTypes.func,
+ PropTypes.number,
+ PropTypes.shape({
+ '__@toStringTag@4090': PropTypes.oneOf(['BigInt']).isRequired,
+ toLocaleString: PropTypes.func.isRequired,
+ toString: PropTypes.func.isRequired,
+ valueOf: PropTypes.func.isRequired,
+ }),
+ PropTypes.shape({
+ '__@iterator@3853': PropTypes.func.isRequired,
+ }),
+ PropTypes.shape({
+ children: PropTypes.node,
+ key: PropTypes.string,
+ props: PropTypes.any.isRequired,
+ type: PropTypes.oneOfType([PropTypes.func, PropTypes.string]).isRequired,
+ }),
+ PropTypes.shape({
+ '__@toStringTag@4090': PropTypes.string.isRequired,
+ catch: PropTypes.func.isRequired,
+ finally: PropTypes.func.isRequired,
+ then: PropTypes.func.isRequired,
+ }),
+ PropTypes.string,
+ PropTypes.bool,
+ ]),
+ /**
+ * @ignore
+ */
+ container: PropTypes.oneOfType([
+ (props, propName) => {
+ if (props[propName] == null) {
+ return new Error(`Prop '${propName}' is required but wasn't specified`);
+ }
+ if (typeof props[propName] !== 'object' || props[propName].nodeType !== 1) {
+ return new Error(`Expected prop '${propName}' to be of type Element`);
+ }
+ return null;
+ },
+ PropTypes.func,
+ ]),
+ /**
+ * @ignore
+ */
+ disablePortal: PropTypes.bool,
+ /**
+ * @ignore
+ */
+ keepMounted: PropTypes.bool,
+ /**
+ * @ignore
+ */
+ middleware: PropTypes.arrayOf(
+ PropTypes.shape({
+ fn: PropTypes.func.isRequired,
+ name: PropTypes.string.isRequired,
+ options: PropTypes.any,
+ }),
+ ),
+ /**
+ * @ignore
+ */
+ open: PropTypes.bool.isRequired,
+ /**
+ * @ignore
+ */
+ placement: PropTypes.oneOf([
+ 'bottom-end',
+ 'bottom-start',
+ 'bottom',
+ 'left-end',
+ 'left-start',
+ 'left',
+ 'right-end',
+ 'right-start',
+ 'right',
+ 'top-end',
+ 'top-start',
+ 'top',
+ ]),
+ /**
+ * @ignore
+ */
+ popperRef: PropTypes.oneOfType([
+ PropTypes.func,
+ PropTypes.shape({
+ current: PropTypes.shape({
+ update: PropTypes.func.isRequired,
+ }),
+ }),
+ ]),
+ /**
+ * @ignore
+ */
+ strategy: PropTypes.oneOf(['absolute', 'fixed']),
+ /**
+ * @ignore
+ */
+ transform: PropTypes.bool,
+ /**
+ * @ignore
+ */
+ transition: PropTypes.bool,
+} as any;
+
+export default FloatingPopup;
diff --git a/packages/mui-material/src/FloatingPopup/FloatingPopup.types.ts b/packages/mui-material/src/FloatingPopup/FloatingPopup.types.ts
new file mode 100644
index 00000000000000..f6b3f8181769fc
--- /dev/null
+++ b/packages/mui-material/src/FloatingPopup/FloatingPopup.types.ts
@@ -0,0 +1,65 @@
+import * as React from 'react';
+import { Placement, Middleware } from '@floating-ui/react-dom';
+
+export interface FloatingPopupActions {
+ update: () => void;
+}
+
+export interface FloatingPopupChildrenProps {
+ placement: Placement;
+ TransitionProps?: FloatingPopupTransitionProps | undefined;
+ arrowStyles: React.CSSProperties;
+ anchorHidden: boolean;
+ isPositioned: boolean;
+}
+
+export interface FloatingPopupTransitionProps {
+ in: boolean;
+ onEnter: () => void;
+ onExited: () => void;
+}
+
+export interface VirtualElement {
+ getBoundingClientRect: () =>
+ | DOMRect
+ | {
+ width: number;
+ height: number;
+ top: number;
+ right: number;
+ bottom: number;
+ left: number;
+ x?: number | undefined;
+ y?: number | undefined;
+ };
+}
+
+export interface FloatingPopupProps extends Omit, 'children'> {
+ // --- Core positioning ---
+ anchorEl?: HTMLElement | VirtualElement | (() => HTMLElement | VirtualElement) | null | undefined;
+ open: boolean;
+ placement?: Placement | undefined;
+ strategy?: 'absolute' | 'fixed' | undefined;
+ middleware?: Middleware[] | undefined;
+ transform?: boolean | undefined;
+
+ // --- Children ---
+ children?: React.ReactNode | ((props: FloatingPopupChildrenProps) => React.ReactNode);
+ transition?: boolean | undefined;
+
+ // --- Arrow ---
+ /**
+ * The arrow element to position. Preferred: pass the element from `useState`.
+ * Also works: `RefObject` (resolved lazily via Derivable pattern + useLayoutEffect).
+ */
+ arrowRef?: React.RefObject | HTMLElement | null | undefined;
+ arrowPadding?: number | undefined;
+
+ // --- DOM ---
+ disablePortal?: boolean | undefined;
+ container?: Element | (() => Element) | undefined;
+ keepMounted?: boolean | undefined;
+
+ // --- Imperative ---
+ popperRef?: React.Ref | undefined;
+}
diff --git a/packages/mui-material/src/FloatingPopup/index.ts b/packages/mui-material/src/FloatingPopup/index.ts
new file mode 100644
index 00000000000000..878b69a45dd273
--- /dev/null
+++ b/packages/mui-material/src/FloatingPopup/index.ts
@@ -0,0 +1,2 @@
+export { default } from './FloatingPopup';
+export * from './FloatingPopup.types';
diff --git a/packages/mui-material/src/Popper/BasePopper.tsx b/packages/mui-material/src/Popper/BasePopper.tsx
index 4c32775a506c15..f4e0eaca287c1b 100644
--- a/packages/mui-material/src/Popper/BasePopper.tsx
+++ b/packages/mui-material/src/Popper/BasePopper.tsx
@@ -94,6 +94,10 @@ const PopperTooltip = React.forwardRef(funct
TransitionProps,
// @ts-ignore internal logic
ownerState: ownerStateProp, // prevent from spreading to DOM, it can come from the parent component e.g. Select.
+ // @ts-ignore — Tooltip passes these for FloatingPopup compat; not used by BasePopper
+ arrowRef,
+ // @ts-ignore
+ arrowPadding,
...other
} = props;
diff --git a/packages/mui-material/src/Tooltip/Tooltip.d.ts b/packages/mui-material/src/Tooltip/Tooltip.d.ts
index 6f915e493a3eff..f45e2d37a991a0 100644
--- a/packages/mui-material/src/Tooltip/Tooltip.d.ts
+++ b/packages/mui-material/src/Tooltip/Tooltip.d.ts
@@ -5,9 +5,13 @@ import { Theme } from '../styles';
import { InternalStandardProps as StandardProps } from '../internal';
import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';
import { TransitionProps } from '../transitions/transition';
+import { FloatingPopupProps } from '../FloatingPopup';
import { TooltipClasses } from './tooltipClasses';
-export interface TooltipPopperSlotPropsOverrides {}
+export interface TooltipPopperSlotPropsOverrides extends Pick<
+ FloatingPopupProps,
+ 'middleware' | 'strategy' | 'transform' | 'arrowPadding'
+> {}
export interface TooltipTransitionSlotPropsOverrides {}
diff --git a/packages/mui-material/src/Tooltip/Tooltip.floating.spec.tsx b/packages/mui-material/src/Tooltip/Tooltip.floating.spec.tsx
new file mode 100644
index 00000000000000..8581206db6e413
--- /dev/null
+++ b/packages/mui-material/src/Tooltip/Tooltip.floating.spec.tsx
@@ -0,0 +1,111 @@
+import * as React from 'react';
+import { offset, flip, shift, Middleware } from '@floating-ui/react-dom';
+import Tooltip from '@mui/material/Tooltip';
+import FloatingPopup from '@mui/material/FloatingPopup';
+
+// FloatingPopup can be passed as the popper slot
+
+ Hover
+ ;
+
+// FloatingPopup-specific slotProps compile without `as any`
+
+ Hover
+ ;
+
+// Arrow + FloatingPopup-specific props
+
+ Hover
+ ;
+
+// Standard Popper props still accepted alongside FloatingPopup props
+
+ Hover
+ ;
+
+// Middleware as a variable
+const middleware: Middleware[] = [offset(8), flip(), shift()];
+
+ Hover
+ ;
+
+// Without FloatingPopup slot — standard Popper slotProps still work
+
+ Hover
+ ;
+
+// slotProps.popper as a function (ownerState callback form)
+ ({
+ strategy: 'fixed' as const,
+ middleware: [offset(8)],
+ }),
+ }}
+>
+ Hover
+ ;
+
+// All slot overrides together
+
+ Hover
+ ;
diff --git a/packages/mui-material/src/Tooltip/Tooltip.floating.test.tsx b/packages/mui-material/src/Tooltip/Tooltip.floating.test.tsx
new file mode 100644
index 00000000000000..d48dae174d7bf2
--- /dev/null
+++ b/packages/mui-material/src/Tooltip/Tooltip.floating.test.tsx
@@ -0,0 +1,836 @@
+import * as React from 'react';
+import { expect } from 'chai';
+import { spy } from 'sinon';
+import {
+ act,
+ createRenderer,
+ fireEvent,
+ flushMicrotasks,
+ screen,
+ simulatePointerDevice,
+ isJsdom,
+} from '@mui/internal-test-utils';
+import { offset } from '@floating-ui/react-dom';
+import Tooltip from '@mui/material/Tooltip';
+import FloatingPopup from '@mui/material/FloatingPopup';
+// @ts-ignore — testReset is exported from Tooltip.js but not declared in Tooltip.d.ts (test-only export)
+import { testReset } from './Tooltip';
+
+/**
+ * Integration tests for Tooltip with FloatingPopup as the popper slot.
+ *
+ * FloatingPopup uses async computePosition from floating-ui.
+ * All fake-timer tests must use `await clock.tickAsync()` (not `clock.tick()`)
+ * to flush the microtask queue so positioning completes and the FOUC guard
+ * (`visibility: hidden`) is removed.
+ *
+ * user-event is not used here because createRenderer's userEvent.setup()
+ * does not configure `advanceTimers`, causing deadlocks with fake timers.
+ * Tooltip's enterDelay/leaveDelay/transition behavior requires fake timers
+ * for all interactive tests.
+ */
+describe('
+ Trigger
+ ,
+ );
+ // Flush async computePosition so visibility:hidden is removed
+ await flushMicrotasks();
+ expect(screen.getByText('Hello World')).not.to.equal(null);
+ });
+
+ it('should not render tooltip content when closed', () => {
+ render(
+
+ Trigger
+ ,
+ );
+ expect(screen.queryByText('Hello World')).to.equal(null);
+ });
+
+ it('should have role="tooltip" on the popup', async () => {
+ render(
+
+ Trigger
+ ,
+ );
+ // Flush async computePosition so visibility:hidden is removed —
+ // getByRole skips elements with visibility:hidden
+ await flushMicrotasks();
+ expect(screen.getByRole('tooltip')).not.to.equal(null);
+ });
+
+ it('should set data-popper-placement on the floating element', () => {
+ render(
+
+ Trigger
+ ,
+ );
+ const floating = document.querySelector('[data-popper-placement]');
+ expect(floating).not.to.equal(null);
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Mouse interaction
+ // ──────────────────────────────────────────────
+
+ describe('mouse interaction', () => {
+ clock.withFakeTimers();
+
+ it('should open on mouseOver and close on mouseLeave', async () => {
+ const transitionTimeout = 10;
+ render(
+
+ Trigger
+ ,
+ );
+
+ fireEvent.mouseOver(screen.getByRole('button'));
+ await clock.tickAsync(100); // default enterDelay
+ expect(screen.getByRole('tooltip')).toBeVisible();
+
+ fireEvent.mouseLeave(screen.getByRole('button'));
+ await clock.tickAsync(0);
+ await clock.tickAsync(transitionTimeout);
+ expect(screen.queryByRole('tooltip')).to.equal(null);
+ });
+
+ it('should respect enterDelay', async () => {
+ render(
+
+ Trigger
+ ,
+ );
+
+ fireEvent.mouseOver(screen.getByRole('button'));
+ await clock.tickAsync(100);
+ expect(screen.queryByRole('tooltip')).to.equal(null);
+
+ await clock.tickAsync(100);
+ expect(screen.getByRole('tooltip')).toBeVisible();
+ });
+
+ it('should respect leaveDelay', async () => {
+ render(
+
+ Trigger
+ ,
+ );
+
+ fireEvent.mouseOver(screen.getByRole('button'));
+ await clock.tickAsync(100); // default enterDelay
+ expect(screen.getByRole('tooltip')).toBeVisible();
+
+ fireEvent.mouseLeave(screen.getByRole('button'));
+ await clock.tickAsync(100);
+ // Still visible during leaveDelay
+ expect(screen.getByRole('tooltip')).toBeVisible();
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Keyboard interaction
+ // ──────────────────────────────────────────────
+
+ describe('keyboard interaction', () => {
+ clock.withFakeTimers();
+
+ it('should close on Escape', async () => {
+ const transitionTimeout = 10;
+ render(
+
+ Trigger
+ ,
+ );
+
+ fireEvent.mouseOver(screen.getByRole('button'));
+ await clock.tickAsync(100); // default enterDelay
+ expect(screen.getByRole('tooltip')).toBeVisible();
+
+ fireEvent.keyDown(document.activeElement || document.body, { key: 'Escape' });
+ await clock.tickAsync(transitionTimeout);
+ expect(screen.queryByRole('tooltip')).to.equal(null);
+ });
+
+ it.skipIf(isJsdom())('should open on focus-visible', async () => {
+ simulatePointerDevice();
+ render(
+
+ Trigger
+ ,
+ );
+
+ const button = screen.getByRole('button');
+ await act(async () => {
+ button.blur();
+ });
+ fireEvent.keyDown(document.body, { key: 'Tab' });
+ await act(async () => {
+ button.focus();
+ });
+
+ await clock.tickAsync(100); // default enterDelay
+ expect(screen.getByRole('tooltip')).toBeVisible();
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Touch interaction
+ // ──────────────────────────────────────────────
+
+ describe('touch interaction', () => {
+ clock.withFakeTimers();
+
+ it('should open on long press', async () => {
+ render(
+
+ Trigger
+ ,
+ );
+
+ fireEvent.touchStart(screen.getByRole('button'));
+ await clock.tickAsync(700 + 100); // enterTouchDelay + enterDelay
+ expect(screen.getByRole('tooltip')).toBeVisible();
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Accessibility
+ // ──────────────────────────────────────────────
+
+ describe('accessibility', () => {
+ it('should label the trigger with the tooltip title', () => {
+ render(
+
+ Trigger
+ ,
+ );
+ const button = screen.getByRole('button');
+ expect(button).to.have.attribute('aria-label', 'Accessible tooltip');
+ });
+
+ it('should set aria-describedby when describeChild is true', () => {
+ render(
+
+ Trigger
+ ,
+ );
+ const button = screen.getByRole('button');
+ expect(button.getAttribute('aria-describedby')).not.to.equal(null);
+ });
+
+ it('should not set aria-describedby when closed', () => {
+ render(
+
+ Trigger
+ ,
+ );
+ const button = screen.getByRole('button');
+ expect(button.getAttribute('aria-describedby')).to.equal(null);
+ });
+
+ it('should connect trigger aria-describedby to tooltip id', async () => {
+ render(
+
+ Trigger
+ ,
+ );
+ await flushMicrotasks();
+ const button = screen.getByRole('button');
+ const describedById = button.getAttribute('aria-describedby');
+ const tooltip = document.getElementById(describedById!);
+ expect(tooltip).not.to.equal(null);
+ expect(tooltip!.textContent).to.include('Connected');
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Placement
+ // ──────────────────────────────────────────────
+
+ describe('placement', () => {
+ const placements = [
+ 'top',
+ 'top-start',
+ 'top-end',
+ 'bottom',
+ 'bottom-start',
+ 'bottom-end',
+ 'left',
+ 'left-start',
+ 'left-end',
+ 'right',
+ 'right-start',
+ 'right-end',
+ ] as const;
+
+ placements.forEach((placement) => {
+ it(`should render with placement="${placement}"`, () => {
+ render(
+
+ Trigger
+ ,
+ );
+ expect(screen.getByText(`Placement ${placement}`)).not.to.equal(null);
+ });
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Arrow
+ // ──────────────────────────────────────────────
+
+ describe('arrow', () => {
+ it('should render the arrow element', () => {
+ render(
+
+ Trigger
+ ,
+ );
+ expect(screen.getByText('Arrow tooltip')).not.to.equal(null);
+ const arrowEl = document.querySelector('.MuiTooltip-arrow');
+ expect(arrowEl).not.to.equal(null);
+ });
+
+ it('should apply position:absolute to the arrow element', async () => {
+ render(
+
+ Trigger
+ ,
+ );
+ // Flush async computePosition so middlewareData.arrow is populated
+ await flushMicrotasks();
+ const arrowEl = document.querySelector('.MuiTooltip-arrow') as HTMLElement;
+ expect(arrowEl).not.to.equal(null);
+ expect(arrowEl!.style.position).to.equal('absolute');
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Transition
+ // ──────────────────────────────────────────────
+
+ describe('transition', () => {
+ clock.withFakeTimers();
+
+ it('should unmount after exit transition', async () => {
+ const transitionTimeout = 10;
+ render(
+
+ Trigger
+ ,
+ );
+
+ fireEvent.mouseOver(screen.getByRole('button'));
+ await clock.tickAsync(100); // default enterDelay
+ expect(screen.getByRole('tooltip')).toBeVisible();
+
+ fireEvent.mouseLeave(screen.getByRole('button'));
+ await clock.tickAsync(0);
+ await clock.tickAsync(transitionTimeout);
+ expect(screen.queryByRole('tooltip')).to.equal(null);
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // followCursor
+ // ──────────────────────────────────────────────
+
+ describe('followCursor', () => {
+ clock.withFakeTimers();
+
+ it('should open and track cursor', async () => {
+ render(
+
+ Trigger
+ ,
+ );
+
+ fireEvent.mouseOver(screen.getByRole('button'), {
+ clientX: 100,
+ clientY: 200,
+ });
+ await clock.tickAsync(100); // default enterDelay
+
+ expect(screen.getByRole('tooltip')).toBeVisible();
+ });
+
+ it('should stay visible after mouse move within trigger', async () => {
+ render(
+
+ Trigger
+ ,
+ );
+
+ const button = screen.getByRole('button');
+ fireEvent.mouseOver(button, { clientX: 50, clientY: 50 });
+ await clock.tickAsync(100); // default enterDelay
+ expect(screen.getByRole('tooltip')).toBeVisible();
+
+ fireEvent.mouseMove(button, { clientX: 100, clientY: 100 });
+ await flushMicrotasks();
+ expect(screen.getByRole('tooltip')).toBeVisible();
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // keepMounted
+ // ──────────────────────────────────────────────
+
+ describe('keepMounted', () => {
+ it('should keep the tooltip in the DOM when closed', () => {
+ render(
+
+ Trigger
+ ,
+ );
+ expect(screen.getByText('Persistent')).not.to.equal(null);
+ });
+
+ it('should hide with display:none when closed and keepMounted', () => {
+ render(
+
+ Trigger
+ ,
+ );
+ const floating = document.querySelector('[data-popper-placement]') as HTMLElement;
+ expect(floating!.style.display).to.equal('none');
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // slotProps passthrough
+ // ──────────────────────────────────────────────
+
+ describe('slotProps.popper', () => {
+ it('should forward data attributes to the floating element', () => {
+ render(
+ }}
+ >
+ Trigger
+ ,
+ );
+ expect(screen.getByTestId('my-popper')).not.to.equal(null);
+ });
+
+ it('should forward strategy=fixed to FloatingPopup', () => {
+ render(
+
+ Trigger
+ ,
+ );
+ const floating = document.querySelector('[data-popper-placement]') as HTMLElement;
+ expect(floating!.style.position).to.equal('fixed');
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // CSS variables
+ // ──────────────────────────────────────────────
+
+ describe('CSS variables', () => {
+ it.skipIf(isJsdom())(
+ 'should set --anchor-width and --anchor-height on the floating element',
+ async () => {
+ render(
+
+ Trigger
+ ,
+ );
+ // Flush async computePosition so anchorMetrics middleware populates data
+ await flushMicrotasks();
+ const floating = document.querySelector('[data-popper-placement]') as HTMLElement;
+ expect(floating).not.to.equal(null);
+ const anchorWidth = floating!.style.getPropertyValue('--anchor-width');
+ const anchorHeight = floating!.style.getPropertyValue('--anchor-height');
+ expect(anchorWidth).to.match(/^\d+(\.\d+)?px$/);
+ expect(anchorHeight).to.match(/^\d+(\.\d+)?px$/);
+ },
+ );
+ });
+
+ // ──────────────────────────────────────────────
+ // Callbacks
+ // ──────────────────────────────────────────────
+
+ describe('callbacks', () => {
+ clock.withFakeTimers();
+
+ it('should call onOpen when tooltip opens', async () => {
+ const handleOpen = spy();
+ render(
+
+ Trigger
+ ,
+ );
+
+ fireEvent.mouseOver(screen.getByRole('button'));
+ await clock.tickAsync(100); // default enterDelay
+ expect(handleOpen.callCount).to.equal(1);
+ });
+
+ it('should call onClose when tooltip closes', async () => {
+ const handleClose = spy();
+ const transitionTimeout = 10;
+ render(
+
+ Trigger
+ ,
+ );
+
+ fireEvent.mouseOver(screen.getByRole('button'));
+ await clock.tickAsync(100); // default enterDelay
+
+ fireEvent.mouseLeave(screen.getByRole('button'));
+ await clock.tickAsync(0);
+ expect(handleClose.callCount).to.equal(1);
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Dynamic title
+ // ──────────────────────────────────────────────
+
+ describe('dynamic title', () => {
+ it('should update content when title changes', () => {
+ const { setProps } = render(
+
+ Trigger
+ ,
+ );
+ expect(screen.getByText('First')).not.to.equal(null);
+
+ setProps({ title: 'Second' });
+ expect(screen.getByText('Second')).not.to.equal(null);
+ });
+
+ it('should close when title becomes empty string', () => {
+ const { setProps } = render(
+
+ Trigger
+ ,
+ );
+ expect(screen.getByText('Hello')).not.to.equal(null);
+
+ setProps({ title: '' });
+ expect(screen.queryByText('Hello')).to.equal(null);
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // disablePortal
+ // ──────────────────────────────────────────────
+
+ describe('disablePortal', () => {
+ it('should render inline when disablePortal is true', () => {
+ const { container } = render(
+
+ Trigger
+ ,
+ );
+ expect(container.querySelector('[data-popper-placement]')).not.to.equal(null);
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Multiple tooltips
+ // ──────────────────────────────────────────────
+
+ describe('multiple tooltips', () => {
+ clock.withFakeTimers();
+
+ it('should switch between tooltips', async () => {
+ const transitionTimeout = 10;
+ render(
+
+
+ Button A
+
+
+ Button B
+
+ ,
+ );
+
+ fireEvent.mouseOver(screen.getByText('Button A'));
+ await clock.tickAsync(100); // default enterDelay
+ expect(screen.getByText('Tooltip A')).not.to.equal(null);
+
+ fireEvent.mouseLeave(screen.getByText('Button A'));
+ await clock.tickAsync(0);
+ await clock.tickAsync(transitionTimeout);
+ fireEvent.mouseOver(screen.getByText('Button B'));
+ await clock.tickAsync(100); // default enterDelay
+ expect(screen.getByText('Tooltip B')).not.to.equal(null);
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Custom middleware
+ // ──────────────────────────────────────────────
+
+ describe('custom middleware', () => {
+ it('should accept custom middleware via slotProps.popper', () => {
+ render(
+
+ Trigger
+ ,
+ );
+ expect(screen.getByText('With middleware')).not.to.equal(null);
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Arrow + custom middleware
+ // ──────────────────────────────────────────────
+
+ describe('arrow with custom middleware', () => {
+ it('should position arrow even with custom middleware', async () => {
+ render(
+
+ Trigger
+ ,
+ );
+ await flushMicrotasks();
+ const arrowEl = document.querySelector('.MuiTooltip-arrow') as HTMLElement;
+ expect(arrowEl).not.to.equal(null);
+ expect(arrowEl!.style.position).to.equal('absolute');
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Rapid interactions
+ // ──────────────────────────────────────────────
+
+ describe('rapid interactions', () => {
+ clock.withFakeTimers();
+
+ it('should not crash during rapid hover in/out', async () => {
+ const transitionTimeout = 10;
+ render(
+
+ Trigger
+ ,
+ );
+ const button = screen.getByRole('button');
+
+ for (let i = 0; i < 10; i += 1) {
+ fireEvent.mouseOver(button);
+ // eslint-disable-next-line no-await-in-loop
+ await clock.tickAsync(10);
+ fireEvent.mouseLeave(button);
+ // eslint-disable-next-line no-await-in-loop
+ await clock.tickAsync(10);
+ }
+
+ await clock.tickAsync(transitionTimeout + 50);
+ expect(screen.queryByRole('tooltip')).to.equal(null);
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Ref forwarding on trigger
+ // ──────────────────────────────────────────────
+
+ describe('ref forwarding', () => {
+ it('should forward ref on the trigger element', () => {
+ const ref = React.createRef();
+ render(
+
+ Trigger
+ ,
+ );
+ expect(ref.current).not.to.equal(null);
+ expect(ref.current).to.be.instanceof(window.HTMLButtonElement);
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Disabled trigger
+ // ──────────────────────────────────────────────
+
+ describe('disabled trigger', () => {
+ clock.withFakeTimers();
+
+ it('should open on hover for disabled button (via internal span wrapper)', async () => {
+ expect(() => {
+ render(
+
+
+ Disabled
+
+ ,
+ );
+ }).toWarnDev('MUI: You are providing a disabled `button` child to the Tooltip component.');
+
+ const wrapper = screen.getByText('Disabled').closest('span');
+ if (wrapper) {
+ fireEvent.mouseOver(wrapper);
+ await clock.tickAsync(100); // default enterDelay
+ expect(screen.getByRole('tooltip')).toBeVisible();
+ }
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // Controlled open
+ // ──────────────────────────────────────────────
+
+ describe('controlled open', () => {
+ it('should stay open when open=true regardless of interactions', async () => {
+ render(
+
+ Trigger
+ ,
+ );
+ await flushMicrotasks();
+ expect(screen.getByRole('tooltip')).toBeVisible();
+ });
+
+ it('should stay closed when open=false regardless of interactions', () => {
+ render(
+
+ Trigger
+ ,
+ );
+ expect(screen.queryByRole('tooltip')).to.equal(null);
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // JSX title
+ // ──────────────────────────────────────────────
+
+ describe('JSX title', () => {
+ it('should render JSX content as tooltip title', () => {
+ render(
+
+ Bold text
+
+ }
+ open
+ slots={{ popper: FloatingPopup }}
+ >
+ Trigger
+ ,
+ );
+ expect(screen.getByText('Bold')).not.to.equal(null);
+ expect(screen.getByText('Bold').tagName).to.equal('STRONG');
+ });
+ });
+
+ // ──────────────────────────────────────────────
+ // FOUC prevention
+ // ──────────────────────────────────────────────
+
+ describe('FOUC prevention', () => {
+ it('should have visibility:hidden before positioning completes', () => {
+ render(
+
+ Trigger
+ ,
+ );
+ const floating = document.querySelector('[data-popper-placement]') as HTMLElement;
+ expect(floating).not.to.equal(null);
+ expect(floating!.style.visibility).to.equal('hidden');
+ });
+
+ it('should remove visibility:hidden after positioning completes', async () => {
+ render(
+
+ Trigger
+ ,
+ );
+ await flushMicrotasks();
+ const floating = document.querySelector('[data-popper-placement]') as HTMLElement;
+ expect(floating!.style.visibility).not.to.equal('hidden');
+ });
+ });
+});
diff --git a/packages/mui-material/src/Tooltip/Tooltip.js b/packages/mui-material/src/Tooltip/Tooltip.js
index 68e397b0855f62..c24131c2b51615 100644
--- a/packages/mui-material/src/Tooltip/Tooltip.js
+++ b/packages/mui-material/src/Tooltip/Tooltip.js
@@ -702,7 +702,7 @@ const Tooltip = React.forwardRef(function Tooltip(inProps, ref) {
};
const [PopperSlot, popperSlotProps] = useSlot('popper', {
- elementType: TooltipPopper,
+ elementType: Popper,
externalForwardedProps,
ownerState,
className: classes.popper,
@@ -732,8 +732,8 @@ const Tooltip = React.forwardRef(function Tooltip(inProps, ref) {
return (
{React.cloneElement(children, childrenProps)}
-
{({ TransitionProps: TransitionPropsInner }) => (
)}
-
+
);
});
diff --git a/packages/mui-material/src/index.d.ts b/packages/mui-material/src/index.d.ts
index e0bd2c9ff92a40..8db65f3fec8bc9 100644
--- a/packages/mui-material/src/index.d.ts
+++ b/packages/mui-material/src/index.d.ts
@@ -139,6 +139,9 @@ export * from './Fade';
export { default as FilledInput } from './FilledInput';
export * from './FilledInput';
+export { default as FloatingPopup } from './FloatingPopup';
+export * from './FloatingPopup';
+
export { default as FormControl } from './FormControl';
export * from './FormControl';
diff --git a/packages/mui-material/src/index.js b/packages/mui-material/src/index.js
index 40d568f41ac205..ef1da1d45c6232 100644
--- a/packages/mui-material/src/index.js
+++ b/packages/mui-material/src/index.js
@@ -136,6 +136,9 @@ export * from './Fade';
export { default as FilledInput } from './FilledInput';
export * from './FilledInput';
+export { default as FloatingPopup } from './FloatingPopup';
+export * from './FloatingPopup';
+
export { default as FormControl } from './FormControl';
export * from './FormControl';
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5ef98beb688675..12fd6147d41744 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -295,6 +295,9 @@ importers:
'@emotion/styled':
specifier: catalog:docs
version: 11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
+ '@floating-ui/react-dom':
+ specifier: ^2.1.6
+ version: 2.1.8(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
'@fortawesome/fontawesome-svg-core':
specifier: ^6.7.2
version: 6.7.2
@@ -1138,6 +1141,9 @@ importers:
'@emotion/styled':
specifier: ^11.3.0
version: 11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
+ '@floating-ui/react-dom':
+ specifier: ^2.1.6
+ version: 2.1.8(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
'@mui/core-downloads-tracker':
specifier: workspace:^
version: link:../mui-core-downloads-tracker