fix(headless): correct panel measurement and tabs indicator timing

.changeset/headless-measurement-gaps.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/accordion/accordion-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useAccordionItemContext } from './accordion-context';
 
 export type AccordionPanelProps = ComponentProps<'div'>;
@@ -27,11 +29,13 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  // Measure the content height and keep it in sync via ResizeObserver
  useLayoutEffect(() => {
  if (!mounted) {
@@ -43,8 +47,12 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  return;
  }
 
- // Measure scrollHeight of the panel's content
+ // Measure scrollHeight of the panel's content. Reset flex/grid alignment
+ // first so non-default alignment can't shrink the reported height.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  };
 
@@ -54,9 +62,36 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  // Observe children mutations that affect height
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel height so the
+ // panel flows naturally with its content (CSS var omitted → height: auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => setHeight(undefined));
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to a measured pixel value when closing starts so the exit
+ // transition animates from a concrete height (height: auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  // Skip enter animation for panels that have never been closed

packages/headless/src/primitives/accordion/accordion.test.tsx

@@ -209,11 +209,31 @@ describe('Accordion', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --cl-accordion-panel-height CSS variable on panel', () => {
+ it('pins --cl-accordion-panel-height while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the var) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderAccordion({ defaultValue: ['item1'] });
+ const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned height once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel height so it
+ // flows naturally with its content.
  renderAccordion({ defaultValue: ['item1'] });
  const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
- // Verify the CSS variable is present in the style attribute
- expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ expect(panel.getAttribute('style') ?? '').not.toContain('--cl-accordion-panel-height');
  });
  });
 

packages/headless/src/primitives/collapsible/collapsible-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useCollapsibleContext } from './collapsible-context';
 
 export type CollapsiblePanelProps = ComponentProps<'div'>;
@@ -26,11 +28,13 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  useLayoutEffect(() => {
  if (!mounted) {
  return;
@@ -41,7 +45,12 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  return;
  }
 
+ // Reset flex/grid alignment before measuring so non-default alignment
+ // can't shrink the reported scroll dimensions.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  setWidth(panel.scrollWidth);
  };
@@ -51,9 +60,40 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  const ro = new ResizeObserver(measure);
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel dimensions so the
+ // panel flows naturally with its content (CSS vars omitted → auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => {
+ setHeight(undefined);
+ setWidth(undefined);
+ });
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to measured pixel values when closing starts so the exit
+ // transition animates from concrete dimensions (auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  const effectiveTransitionProps = !hasBeenClosed.current

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -157,16 +157,34 @@ describe('Collapsible', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --collapsible-panel-height CSS variable on panel', () => {
+ it('pins --collapsible-panel-height/width while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the vars) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned dimensions once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel dimensions so
+ // it flows naturally with its content.
  renderCollapsible({ defaultOpen: true });
  const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
- });
-
- it('sets --collapsible-panel-width CSS variable on panel', () => {
- renderCollapsible({ defaultOpen: true });
- const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ const style = panel.getAttribute('style') ?? '';
+ expect(style).not.toContain('--collapsible-panel-height');
+ expect(style).not.toContain('--collapsible-panel-width');
  });
  });
 

packages/headless/src/primitives/tabs/tabs-context.ts

@@ -8,7 +8,11 @@ export interface TabsContextValue {
  tabsId: string;
  registerTab: (value: string, element: HTMLElement | null) => void;
  getTabElement: (value: string) => HTMLElement | null;
- listRef: React.RefObject<HTMLElement>;
+ // The list element is tracked as state (not a ref) so the indicator, a child,
+ // re-renders once the list mounts. A child's layout effect runs before its
+ // parent's ref is attached, so a plain ref would read null on first measure.
+ listElement: HTMLElement | null;
+ setListElement: (element: HTMLElement | null) => void;
  direction: 1 | -1;
 }
 

packages/headless/src/primitives/tabs/tabs-indicator.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import type React from 'react';
-import { useEffect, useRef, useState } from 'react';
+import { useLayoutEffect, useRef, useState } from 'react';
 
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
 import { useTabsContext } from './tabs-context';
@@ -10,7 +10,7 @@ export type TabsIndicatorProps = ComponentProps<'span'>;
 
 export function TabsIndicator(props: TabsIndicatorProps) {
  const { render, ...otherProps } = props;
- const { value, getTabElement, orientation, listRef } = useTabsContext();
+ const { value, getTabElement, orientation, listElement } = useTabsContext();
 
  const [style, setStyle] = useState<React.CSSProperties>({});
  const previousRectRef = useRef<{
@@ -20,9 +20,11 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  height: number;
  } | null>(null);
 
- useEffect(() => {
+ // Measure synchronously before paint so the indicator never commits a frame
+ // at a stale position when the active tab changes.
+ useLayoutEffect(() => {
  const el = getTabElement(value);
- const list = listRef.current;
+ const list = listElement;
  if (!el || !list) {
  return;
  }
@@ -64,7 +66,7 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  ro.observe(el);
  ro.observe(list);
  return () => ro.disconnect();
- }, [value, getTabElement, orientation, listRef]);
+ }, [value, getTabElement, orientation, listElement]);
 
  const defaultProps = {
  'data-cl-slot': 'tabs-indicator',

packages/headless/src/primitives/tabs/tabs-list.tsx

@@ -10,11 +10,11 @@ export type TabsListProps = ComponentProps<'div'>;
 
 export function TabsList(props: TabsListProps) {
  const { render, children, ...otherProps } = props;
- const { orientation, listRef } = useTabsContext();
+ const { orientation, setListElement } = useTabsContext();
 
  return (
  <Composite
- ref={listRef}
+ ref={setListElement}
  orientation={orientation}
  render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
  const defaultProps: Record<string, unknown> = {

packages/headless/src/primitives/tabs/tabs-root.tsx

@@ -23,7 +23,7 @@ export function TabsRoot(props: TabsProps) {
  const tabsId = useId();
  const tabElementsRef = useRef<Map<string, HTMLElement>>(new Map());
  const tabOrderRef = useRef<string[]>([]);
- const listRef = useRef<HTMLElement>(null);
+ const [listElement, setListElement] = useState<HTMLElement | null>(null);
  const valueRef = useRef(value);
  valueRef.current = value;
 
@@ -64,10 +64,11 @@ export function TabsRoot(props: TabsProps) {
  tabsId,
  registerTab,
  getTabElement,
- listRef,
+ listElement,
+ setListElement,
  direction,
  }),
- [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, direction],
+ [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, listElement, direction],
  );
 
  return <TabsContext.Provider value={contextValue}>{children}</TabsContext.Provider>;

packages/headless/src/utils/index.ts

@@ -1,2 +1,3 @@
 export { cssVars } from './css-vars';
+export { resetLayoutStyles } from './reset-layout-styles';
 export { type ComponentProps, type DefaultProps, mergeProps, type RenderProp, renderElement } from './render-element';

packages/headless/src/utils/reset-layout-styles.ts

@@ -0,0 +1,51 @@
+/**
+ * Temporarily forces flex/grid alignment properties to `initial` so the
+ * element's content height can be measured accurately.
+ *
+ * When a panel uses `display: flex` or `display: grid` with a non-default
+ * `justify-content` / `align-items` / `align-content` / `justify-items`, the
+ * alignment can make `scrollHeight`/`scrollWidth` report a value smaller than
+ * the true content size. Resetting these to `initial` before measuring avoids
+ * that distortion.
+ *
+ * The original inline values are restored on the next animation frame so the
+ * forced-initial layout never flashes. The returned cleanup cancels that
+ * scheduled restore and reapplies the original values immediately — call it
+ * from the effect cleanup so a re-run before the frame fires doesn't leak the
+ * forced styles.
+ *
+ * @param element - The element being measured.
+ * @returns A cleanup function that cancels the scheduled restore and restores
+ * the original inline layout styles immediately.
+ */
+export function resetLayoutStyles(element: HTMLElement): () => void {
+ // Capture the value AND its priority flag so an inline `!important` is
+ // restored faithfully (getPropertyValue alone would drop the priority).
+ const keys = ['justify-content', 'align-items', 'align-content', 'justify-items'];
+ const originalLayoutStyles = keys.map(key => ({
+ key,
+ value: element.style.getPropertyValue(key),
+ priority: element.style.getPropertyPriority(key),
+ }));
+
+ keys.forEach(key => {
+ element.style.setProperty(key, 'initial', 'important');
+ });
+
+ function restore() {
+ for (const { key, value, priority } of originalLayoutStyles) {
+ if (value === '') {
+ element.style.removeProperty(key);
+ continue;
+ }
+ element.style.setProperty(key, value, priority);
+ }
+ }
+
+ const frame = requestAnimationFrame(restore);
+
+ return () => {
+ cancelAnimationFrame(frame);
+ restore();
+ };
+}

.changeset/headless-measurement-gaps.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/accordion/accordion-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useAccordionItemContext } from './accordion-context';
 
 export type AccordionPanelProps = ComponentProps<'div'>;
@@ -27,11 +29,13 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  // Measure the content height and keep it in sync via ResizeObserver
  useLayoutEffect(() => {
  if (!mounted) {
@@ -43,8 +47,12 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  return;
  }
 
- // Measure scrollHeight of the panel's content
+ // Measure scrollHeight of the panel's content. Reset flex/grid alignment
+ // first so non-default alignment can't shrink the reported height.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  };
 
@@ -54,9 +62,36 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  // Observe children mutations that affect height
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel height so the
+ // panel flows naturally with its content (CSS var omitted → height: auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => setHeight(undefined));
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to a measured pixel value when closing starts so the exit
+ // transition animates from a concrete height (height: auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  // Skip enter animation for panels that have never been closed

packages/headless/src/primitives/accordion/accordion.test.tsx

@@ -209,11 +209,31 @@ describe('Accordion', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --cl-accordion-panel-height CSS variable on panel', () => {
+ it('pins --cl-accordion-panel-height while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the var) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderAccordion({ defaultValue: ['item1'] });
+ const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned height once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel height so it
+ // flows naturally with its content.
  renderAccordion({ defaultValue: ['item1'] });
  const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
- // Verify the CSS variable is present in the style attribute
- expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ expect(panel.getAttribute('style') ?? '').not.toContain('--cl-accordion-panel-height');
  });
  });
 

packages/headless/src/primitives/collapsible/collapsible-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useCollapsibleContext } from './collapsible-context';
 
 export type CollapsiblePanelProps = ComponentProps<'div'>;
@@ -26,11 +28,13 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  useLayoutEffect(() => {
  if (!mounted) {
  return;
@@ -41,7 +45,12 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  return;
  }
 
+ // Reset flex/grid alignment before measuring so non-default alignment
+ // can't shrink the reported scroll dimensions.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  setWidth(panel.scrollWidth);
  };
@@ -51,9 +60,40 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  const ro = new ResizeObserver(measure);
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel dimensions so the
+ // panel flows naturally with its content (CSS vars omitted → auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => {
+ setHeight(undefined);
+ setWidth(undefined);
+ });
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to measured pixel values when closing starts so the exit
+ // transition animates from concrete dimensions (auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  const effectiveTransitionProps = !hasBeenClosed.current

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -157,16 +157,34 @@ describe('Collapsible', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --collapsible-panel-height CSS variable on panel', () => {
+ it('pins --collapsible-panel-height/width while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the vars) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned dimensions once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel dimensions so
+ // it flows naturally with its content.
  renderCollapsible({ defaultOpen: true });
  const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
- });
-
- it('sets --collapsible-panel-width CSS variable on panel', () => {
- renderCollapsible({ defaultOpen: true });
- const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ const style = panel.getAttribute('style') ?? '';
+ expect(style).not.toContain('--collapsible-panel-height');
+ expect(style).not.toContain('--collapsible-panel-width');
  });
  });
 

packages/headless/src/primitives/tabs/tabs-context.ts

@@ -8,7 +8,11 @@ export interface TabsContextValue {
  tabsId: string;
  registerTab: (value: string, element: HTMLElement | null) => void;
  getTabElement: (value: string) => HTMLElement | null;
- listRef: React.RefObject<HTMLElement>;
+ // The list element is tracked as state (not a ref) so the indicator, a child,
+ // re-renders once the list mounts. A child's layout effect runs before its
+ // parent's ref is attached, so a plain ref would read null on first measure.
+ listElement: HTMLElement | null;
+ setListElement: (element: HTMLElement | null) => void;
  direction: 1 | -1;
 }
 

packages/headless/src/primitives/tabs/tabs-indicator.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import type React from 'react';
-import { useEffect, useRef, useState } from 'react';
+import { useLayoutEffect, useRef, useState } from 'react';
 
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
 import { useTabsContext } from './tabs-context';
@@ -10,7 +10,7 @@ export type TabsIndicatorProps = ComponentProps<'span'>;
 
 export function TabsIndicator(props: TabsIndicatorProps) {
  const { render, ...otherProps } = props;
- const { value, getTabElement, orientation, listRef } = useTabsContext();
+ const { value, getTabElement, orientation, listElement } = useTabsContext();
 
  const [style, setStyle] = useState<React.CSSProperties>({});
  const previousRectRef = useRef<{
@@ -20,9 +20,11 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  height: number;
  } | null>(null);
 
- useEffect(() => {
+ // Measure synchronously before paint so the indicator never commits a frame
+ // at a stale position when the active tab changes.
+ useLayoutEffect(() => {
  const el = getTabElement(value);
- const list = listRef.current;
+ const list = listElement;
  if (!el || !list) {
  return;
  }
@@ -64,7 +66,7 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  ro.observe(el);
  ro.observe(list);
  return () => ro.disconnect();
- }, [value, getTabElement, orientation, listRef]);
+ }, [value, getTabElement, orientation, listElement]);
 
  const defaultProps = {
  'data-cl-slot': 'tabs-indicator',

packages/headless/src/primitives/tabs/tabs-list.tsx

@@ -10,11 +10,11 @@ export type TabsListProps = ComponentProps<'div'>;
 
 export function TabsList(props: TabsListProps) {
  const { render, children, ...otherProps } = props;
- const { orientation, listRef } = useTabsContext();
+ const { orientation, setListElement } = useTabsContext();
 
  return (
  <Composite
- ref={listRef}
+ ref={setListElement}
  orientation={orientation}
  render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
  const defaultProps: Record<string, unknown> = {

packages/headless/src/primitives/tabs/tabs-root.tsx

@@ -23,7 +23,7 @@ export function TabsRoot(props: TabsProps) {
  const tabsId = useId();
  const tabElementsRef = useRef<Map<string, HTMLElement>>(new Map());
  const tabOrderRef = useRef<string[]>([]);
- const listRef = useRef<HTMLElement>(null);
+ const [listElement, setListElement] = useState<HTMLElement | null>(null);
  const valueRef = useRef(value);
  valueRef.current = value;
 
@@ -64,10 +64,11 @@ export function TabsRoot(props: TabsProps) {
  tabsId,
  registerTab,
  getTabElement,
- listRef,
+ listElement,
+ setListElement,
  direction,
  }),
- [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, direction],
+ [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, listElement, direction],
  );
 
  return <TabsContext.Provider value={contextValue}>{children}</TabsContext.Provider>;

packages/headless/src/utils/index.ts

@@ -1,2 +1,3 @@
 export { cssVars } from './css-vars';
+export { resetLayoutStyles } from './reset-layout-styles';
 export { type ComponentProps, type DefaultProps, mergeProps, type RenderProp, renderElement } from './render-element';

packages/headless/src/utils/reset-layout-styles.ts

@@ -0,0 +1,51 @@
+/**
+ * Temporarily forces flex/grid alignment properties to `initial` so the
+ * element's content height can be measured accurately.
+ *
+ * When a panel uses `display: flex` or `display: grid` with a non-default
+ * `justify-content` / `align-items` / `align-content` / `justify-items`, the
+ * alignment can make `scrollHeight`/`scrollWidth` report a value smaller than
+ * the true content size. Resetting these to `initial` before measuring avoids
+ * that distortion.
+ *
+ * The original inline values are restored on the next animation frame so the
+ * forced-initial layout never flashes. The returned cleanup cancels that
+ * scheduled restore and reapplies the original values immediately — call it
+ * from the effect cleanup so a re-run before the frame fires doesn't leak the
+ * forced styles.
+ *
+ * @param element - The element being measured.
+ * @returns A cleanup function that cancels the scheduled restore and restores
+ * the original inline layout styles immediately.
+ */
+export function resetLayoutStyles(element: HTMLElement): () => void {
+ // Capture the value AND its priority flag so an inline `!important` is
+ // restored faithfully (getPropertyValue alone would drop the priority).
+ const keys = ['justify-content', 'align-items', 'align-content', 'justify-items'];
+ const originalLayoutStyles = keys.map(key => ({
+ key,
+ value: element.style.getPropertyValue(key),
+ priority: element.style.getPropertyPriority(key),
+ }));
+
+ keys.forEach(key => {
+ element.style.setProperty(key, 'initial', 'important');
+ });
+
+ function restore() {
+ for (const { key, value, priority } of originalLayoutStyles) {
+ if (value === '') {
+ element.style.removeProperty(key);
+ continue;
+ }
+ element.style.setProperty(key, value, priority);
+ }
+ }
+
+ const frame = requestAnimationFrame(restore);
+
+ return () => {
+ cancelAnimationFrame(frame);
+ restore();
+ };
+}

.changeset/headless-measurement-gaps.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/accordion/accordion-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useAccordionItemContext } from './accordion-context';
 
 export type AccordionPanelProps = ComponentProps<'div'>;
@@ -27,11 +29,13 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  // Measure the content height and keep it in sync via ResizeObserver
  useLayoutEffect(() => {
  if (!mounted) {
@@ -43,8 +47,12 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  return;
  }
 
- // Measure scrollHeight of the panel's content
+ // Measure scrollHeight of the panel's content. Reset flex/grid alignment
+ // first so non-default alignment can't shrink the reported height.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  };
 
@@ -54,9 +62,36 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  // Observe children mutations that affect height
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel height so the
+ // panel flows naturally with its content (CSS var omitted → height: auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => setHeight(undefined));
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to a measured pixel value when closing starts so the exit
+ // transition animates from a concrete height (height: auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  // Skip enter animation for panels that have never been closed

packages/headless/src/primitives/accordion/accordion.test.tsx

@@ -209,11 +209,31 @@ describe('Accordion', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --cl-accordion-panel-height CSS variable on panel', () => {
+ it('pins --cl-accordion-panel-height while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the var) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderAccordion({ defaultValue: ['item1'] });
+ const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned height once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel height so it
+ // flows naturally with its content.
  renderAccordion({ defaultValue: ['item1'] });
  const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
- // Verify the CSS variable is present in the style attribute
- expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ expect(panel.getAttribute('style') ?? '').not.toContain('--cl-accordion-panel-height');
  });
  });
 

packages/headless/src/primitives/collapsible/collapsible-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useCollapsibleContext } from './collapsible-context';
 
 export type CollapsiblePanelProps = ComponentProps<'div'>;
@@ -26,11 +28,13 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  useLayoutEffect(() => {
  if (!mounted) {
  return;
@@ -41,7 +45,12 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  return;
  }
 
+ // Reset flex/grid alignment before measuring so non-default alignment
+ // can't shrink the reported scroll dimensions.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  setWidth(panel.scrollWidth);
  };
@@ -51,9 +60,40 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  const ro = new ResizeObserver(measure);
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel dimensions so the
+ // panel flows naturally with its content (CSS vars omitted → auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => {
+ setHeight(undefined);
+ setWidth(undefined);
+ });
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to measured pixel values when closing starts so the exit
+ // transition animates from concrete dimensions (auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  const effectiveTransitionProps = !hasBeenClosed.current

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -157,16 +157,34 @@ describe('Collapsible', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --collapsible-panel-height CSS variable on panel', () => {
+ it('pins --collapsible-panel-height/width while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the vars) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned dimensions once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel dimensions so
+ // it flows naturally with its content.
  renderCollapsible({ defaultOpen: true });
  const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
- });
-
- it('sets --collapsible-panel-width CSS variable on panel', () => {
- renderCollapsible({ defaultOpen: true });
- const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ const style = panel.getAttribute('style') ?? '';
+ expect(style).not.toContain('--collapsible-panel-height');
+ expect(style).not.toContain('--collapsible-panel-width');
  });
  });
 

packages/headless/src/primitives/tabs/tabs-context.ts

@@ -8,7 +8,11 @@ export interface TabsContextValue {
  tabsId: string;
  registerTab: (value: string, element: HTMLElement | null) => void;
  getTabElement: (value: string) => HTMLElement | null;
- listRef: React.RefObject<HTMLElement>;
+ // The list element is tracked as state (not a ref) so the indicator, a child,
+ // re-renders once the list mounts. A child's layout effect runs before its
+ // parent's ref is attached, so a plain ref would read null on first measure.
+ listElement: HTMLElement | null;
+ setListElement: (element: HTMLElement | null) => void;
  direction: 1 | -1;
 }
 

packages/headless/src/primitives/tabs/tabs-indicator.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import type React from 'react';
-import { useEffect, useRef, useState } from 'react';
+import { useLayoutEffect, useRef, useState } from 'react';
 
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
 import { useTabsContext } from './tabs-context';
@@ -10,7 +10,7 @@ export type TabsIndicatorProps = ComponentProps<'span'>;
 
 export function TabsIndicator(props: TabsIndicatorProps) {
  const { render, ...otherProps } = props;
- const { value, getTabElement, orientation, listRef } = useTabsContext();
+ const { value, getTabElement, orientation, listElement } = useTabsContext();
 
  const [style, setStyle] = useState<React.CSSProperties>({});
  const previousRectRef = useRef<{
@@ -20,9 +20,11 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  height: number;
  } | null>(null);
 
- useEffect(() => {
+ // Measure synchronously before paint so the indicator never commits a frame
+ // at a stale position when the active tab changes.
+ useLayoutEffect(() => {
  const el = getTabElement(value);
- const list = listRef.current;
+ const list = listElement;
  if (!el || !list) {
  return;
  }
@@ -64,7 +66,7 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  ro.observe(el);
  ro.observe(list);
  return () => ro.disconnect();
- }, [value, getTabElement, orientation, listRef]);
+ }, [value, getTabElement, orientation, listElement]);
 
  const defaultProps = {
  'data-cl-slot': 'tabs-indicator',

packages/headless/src/primitives/tabs/tabs-list.tsx

@@ -10,11 +10,11 @@ export type TabsListProps = ComponentProps<'div'>;
 
 export function TabsList(props: TabsListProps) {
  const { render, children, ...otherProps } = props;
- const { orientation, listRef } = useTabsContext();
+ const { orientation, setListElement } = useTabsContext();
 
  return (
  <Composite
- ref={listRef}
+ ref={setListElement}
  orientation={orientation}
  render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
  const defaultProps: Record<string, unknown> = {

packages/headless/src/primitives/tabs/tabs-root.tsx

@@ -23,7 +23,7 @@ export function TabsRoot(props: TabsProps) {
  const tabsId = useId();
  const tabElementsRef = useRef<Map<string, HTMLElement>>(new Map());
  const tabOrderRef = useRef<string[]>([]);
- const listRef = useRef<HTMLElement>(null);
+ const [listElement, setListElement] = useState<HTMLElement | null>(null);
  const valueRef = useRef(value);
  valueRef.current = value;
 
@@ -64,10 +64,11 @@ export function TabsRoot(props: TabsProps) {
  tabsId,
  registerTab,
  getTabElement,
- listRef,
+ listElement,
+ setListElement,
  direction,
  }),
- [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, direction],
+ [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, listElement, direction],
  );
 
  return <TabsContext.Provider value={contextValue}>{children}</TabsContext.Provider>;

packages/headless/src/utils/index.ts

@@ -1,2 +1,3 @@
 export { cssVars } from './css-vars';
+export { resetLayoutStyles } from './reset-layout-styles';
 export { type ComponentProps, type DefaultProps, mergeProps, type RenderProp, renderElement } from './render-element';

packages/headless/src/utils/reset-layout-styles.ts

@@ -0,0 +1,51 @@
+/**
+ * Temporarily forces flex/grid alignment properties to `initial` so the
+ * element's content height can be measured accurately.
+ *
+ * When a panel uses `display: flex` or `display: grid` with a non-default
+ * `justify-content` / `align-items` / `align-content` / `justify-items`, the
+ * alignment can make `scrollHeight`/`scrollWidth` report a value smaller than
+ * the true content size. Resetting these to `initial` before measuring avoids
+ * that distortion.
+ *
+ * The original inline values are restored on the next animation frame so the
+ * forced-initial layout never flashes. The returned cleanup cancels that
+ * scheduled restore and reapplies the original values immediately — call it
+ * from the effect cleanup so a re-run before the frame fires doesn't leak the
+ * forced styles.
+ *
+ * @param element - The element being measured.
+ * @returns A cleanup function that cancels the scheduled restore and restores
+ * the original inline layout styles immediately.
+ */
+export function resetLayoutStyles(element: HTMLElement): () => void {
+ // Capture the value AND its priority flag so an inline `!important` is
+ // restored faithfully (getPropertyValue alone would drop the priority).
+ const keys = ['justify-content', 'align-items', 'align-content', 'justify-items'];
+ const originalLayoutStyles = keys.map(key => ({
+ key,
+ value: element.style.getPropertyValue(key),
+ priority: element.style.getPropertyPriority(key),
+ }));
+
+ keys.forEach(key => {
+ element.style.setProperty(key, 'initial', 'important');
+ });
+
+ function restore() {
+ for (const { key, value, priority } of originalLayoutStyles) {
+ if (value === '') {
+ element.style.removeProperty(key);
+ continue;
+ }
+ element.style.setProperty(key, value, priority);
+ }
+ }
+
+ const frame = requestAnimationFrame(restore);
+
+ return () => {
+ cancelAnimationFrame(frame);
+ restore();
+ };
+}

.changeset/headless-measurement-gaps.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/accordion/accordion-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useAccordionItemContext } from './accordion-context';
 
 export type AccordionPanelProps = ComponentProps<'div'>;
@@ -27,11 +29,13 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  // Measure the content height and keep it in sync via ResizeObserver
  useLayoutEffect(() => {
  if (!mounted) {
@@ -43,8 +47,12 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  return;
  }
 
- // Measure scrollHeight of the panel's content
+ // Measure scrollHeight of the panel's content. Reset flex/grid alignment
+ // first so non-default alignment can't shrink the reported height.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  };
 
@@ -54,9 +62,36 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  // Observe children mutations that affect height
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel height so the
+ // panel flows naturally with its content (CSS var omitted → height: auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => setHeight(undefined));
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to a measured pixel value when closing starts so the exit
+ // transition animates from a concrete height (height: auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  // Skip enter animation for panels that have never been closed

packages/headless/src/primitives/accordion/accordion.test.tsx

@@ -209,11 +209,31 @@ describe('Accordion', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --cl-accordion-panel-height CSS variable on panel', () => {
+ it('pins --cl-accordion-panel-height while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the var) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderAccordion({ defaultValue: ['item1'] });
+ const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned height once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel height so it
+ // flows naturally with its content.
  renderAccordion({ defaultValue: ['item1'] });
  const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
- // Verify the CSS variable is present in the style attribute
- expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ expect(panel.getAttribute('style') ?? '').not.toContain('--cl-accordion-panel-height');
  });
  });
 

packages/headless/src/primitives/collapsible/collapsible-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useCollapsibleContext } from './collapsible-context';
 
 export type CollapsiblePanelProps = ComponentProps<'div'>;
@@ -26,11 +28,13 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  useLayoutEffect(() => {
  if (!mounted) {
  return;
@@ -41,7 +45,12 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  return;
  }
 
+ // Reset flex/grid alignment before measuring so non-default alignment
+ // can't shrink the reported scroll dimensions.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  setWidth(panel.scrollWidth);
  };
@@ -51,9 +60,40 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  const ro = new ResizeObserver(measure);
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel dimensions so the
+ // panel flows naturally with its content (CSS vars omitted → auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => {
+ setHeight(undefined);
+ setWidth(undefined);
+ });
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to measured pixel values when closing starts so the exit
+ // transition animates from concrete dimensions (auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  const effectiveTransitionProps = !hasBeenClosed.current

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -157,16 +157,34 @@ describe('Collapsible', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --collapsible-panel-height CSS variable on panel', () => {
+ it('pins --collapsible-panel-height/width while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the vars) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned dimensions once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel dimensions so
+ // it flows naturally with its content.
  renderCollapsible({ defaultOpen: true });
  const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
- });
-
- it('sets --collapsible-panel-width CSS variable on panel', () => {
- renderCollapsible({ defaultOpen: true });
- const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ const style = panel.getAttribute('style') ?? '';
+ expect(style).not.toContain('--collapsible-panel-height');
+ expect(style).not.toContain('--collapsible-panel-width');
  });
  });
 

packages/headless/src/primitives/tabs/tabs-context.ts

@@ -8,7 +8,11 @@ export interface TabsContextValue {
  tabsId: string;
  registerTab: (value: string, element: HTMLElement | null) => void;
  getTabElement: (value: string) => HTMLElement | null;
- listRef: React.RefObject<HTMLElement>;
+ // The list element is tracked as state (not a ref) so the indicator, a child,
+ // re-renders once the list mounts. A child's layout effect runs before its
+ // parent's ref is attached, so a plain ref would read null on first measure.
+ listElement: HTMLElement | null;
+ setListElement: (element: HTMLElement | null) => void;
  direction: 1 | -1;
 }
 

packages/headless/src/primitives/tabs/tabs-indicator.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import type React from 'react';
-import { useEffect, useRef, useState } from 'react';
+import { useLayoutEffect, useRef, useState } from 'react';
 
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
 import { useTabsContext } from './tabs-context';
@@ -10,7 +10,7 @@ export type TabsIndicatorProps = ComponentProps<'span'>;
 
 export function TabsIndicator(props: TabsIndicatorProps) {
  const { render, ...otherProps } = props;
- const { value, getTabElement, orientation, listRef } = useTabsContext();
+ const { value, getTabElement, orientation, listElement } = useTabsContext();
 
  const [style, setStyle] = useState<React.CSSProperties>({});
  const previousRectRef = useRef<{
@@ -20,9 +20,11 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  height: number;
  } | null>(null);
 
- useEffect(() => {
+ // Measure synchronously before paint so the indicator never commits a frame
+ // at a stale position when the active tab changes.
+ useLayoutEffect(() => {
  const el = getTabElement(value);
- const list = listRef.current;
+ const list = listElement;
  if (!el || !list) {
  return;
  }
@@ -64,7 +66,7 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  ro.observe(el);
  ro.observe(list);
  return () => ro.disconnect();
- }, [value, getTabElement, orientation, listRef]);
+ }, [value, getTabElement, orientation, listElement]);
 
  const defaultProps = {
  'data-cl-slot': 'tabs-indicator',

packages/headless/src/primitives/tabs/tabs-list.tsx

@@ -10,11 +10,11 @@ export type TabsListProps = ComponentProps<'div'>;
 
 export function TabsList(props: TabsListProps) {
  const { render, children, ...otherProps } = props;
- const { orientation, listRef } = useTabsContext();
+ const { orientation, setListElement } = useTabsContext();
 
  return (
  <Composite
- ref={listRef}
+ ref={setListElement}
  orientation={orientation}
  render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
  const defaultProps: Record<string, unknown> = {

packages/headless/src/primitives/tabs/tabs-root.tsx

@@ -23,7 +23,7 @@ export function TabsRoot(props: TabsProps) {
  const tabsId = useId();
  const tabElementsRef = useRef<Map<string, HTMLElement>>(new Map());
  const tabOrderRef = useRef<string[]>([]);
- const listRef = useRef<HTMLElement>(null);
+ const [listElement, setListElement] = useState<HTMLElement | null>(null);
  const valueRef = useRef(value);
  valueRef.current = value;
 
@@ -64,10 +64,11 @@ export function TabsRoot(props: TabsProps) {
  tabsId,
  registerTab,
  getTabElement,
- listRef,
+ listElement,
+ setListElement,
  direction,
  }),
- [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, direction],
+ [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, listElement, direction],
  );
 
  return <TabsContext.Provider value={contextValue}>{children}</TabsContext.Provider>;

packages/headless/src/utils/index.ts

@@ -1,2 +1,3 @@
 export { cssVars } from './css-vars';
+export { resetLayoutStyles } from './reset-layout-styles';
 export { type ComponentProps, type DefaultProps, mergeProps, type RenderProp, renderElement } from './render-element';

packages/headless/src/utils/reset-layout-styles.ts

@@ -0,0 +1,51 @@
+/**
+ * Temporarily forces flex/grid alignment properties to `initial` so the
+ * element's content height can be measured accurately.
+ *
+ * When a panel uses `display: flex` or `display: grid` with a non-default
+ * `justify-content` / `align-items` / `align-content` / `justify-items`, the
+ * alignment can make `scrollHeight`/`scrollWidth` report a value smaller than
+ * the true content size. Resetting these to `initial` before measuring avoids
+ * that distortion.
+ *
+ * The original inline values are restored on the next animation frame so the
+ * forced-initial layout never flashes. The returned cleanup cancels that
+ * scheduled restore and reapplies the original values immediately — call it
+ * from the effect cleanup so a re-run before the frame fires doesn't leak the
+ * forced styles.
+ *
+ * @param element - The element being measured.
+ * @returns A cleanup function that cancels the scheduled restore and restores
+ * the original inline layout styles immediately.
+ */
+export function resetLayoutStyles(element: HTMLElement): () => void {
+ // Capture the value AND its priority flag so an inline `!important` is
+ // restored faithfully (getPropertyValue alone would drop the priority).
+ const keys = ['justify-content', 'align-items', 'align-content', 'justify-items'];
+ const originalLayoutStyles = keys.map(key => ({
+ key,
+ value: element.style.getPropertyValue(key),
+ priority: element.style.getPropertyPriority(key),
+ }));
+
+ keys.forEach(key => {
+ element.style.setProperty(key, 'initial', 'important');
+ });
+
+ function restore() {
+ for (const { key, value, priority } of originalLayoutStyles) {
+ if (value === '') {
+ element.style.removeProperty(key);
+ continue;
+ }
+ element.style.setProperty(key, value, priority);
+ }
+ }
+
+ const frame = requestAnimationFrame(restore);
+
+ return () => {
+ cancelAnimationFrame(frame);
+ restore();
+ };
+}

.changeset/headless-measurement-gaps.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/accordion/accordion-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useAccordionItemContext } from './accordion-context';
 
 export type AccordionPanelProps = ComponentProps<'div'>;
@@ -27,11 +29,13 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  // Measure the content height and keep it in sync via ResizeObserver
  useLayoutEffect(() => {
  if (!mounted) {
@@ -43,8 +47,12 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  return;
  }
 
- // Measure scrollHeight of the panel's content
+ // Measure scrollHeight of the panel's content. Reset flex/grid alignment
+ // first so non-default alignment can't shrink the reported height.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  };
 
@@ -54,9 +62,36 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  // Observe children mutations that affect height
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel height so the
+ // panel flows naturally with its content (CSS var omitted → height: auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => setHeight(undefined));
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to a measured pixel value when closing starts so the exit
+ // transition animates from a concrete height (height: auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  // Skip enter animation for panels that have never been closed

packages/headless/src/primitives/accordion/accordion.test.tsx

@@ -209,11 +209,31 @@ describe('Accordion', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --cl-accordion-panel-height CSS variable on panel', () => {
+ it('pins --cl-accordion-panel-height while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the var) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderAccordion({ defaultValue: ['item1'] });
+ const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned height once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel height so it
+ // flows naturally with its content.
  renderAccordion({ defaultValue: ['item1'] });
  const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
- // Verify the CSS variable is present in the style attribute
- expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ expect(panel.getAttribute('style') ?? '').not.toContain('--cl-accordion-panel-height');
  });
  });
 

packages/headless/src/primitives/collapsible/collapsible-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useCollapsibleContext } from './collapsible-context';
 
 export type CollapsiblePanelProps = ComponentProps<'div'>;
@@ -26,11 +28,13 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  useLayoutEffect(() => {
  if (!mounted) {
  return;
@@ -41,7 +45,12 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  return;
  }
 
+ // Reset flex/grid alignment before measuring so non-default alignment
+ // can't shrink the reported scroll dimensions.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  setWidth(panel.scrollWidth);
  };
@@ -51,9 +60,40 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  const ro = new ResizeObserver(measure);
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel dimensions so the
+ // panel flows naturally with its content (CSS vars omitted → auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => {
+ setHeight(undefined);
+ setWidth(undefined);
+ });
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to measured pixel values when closing starts so the exit
+ // transition animates from concrete dimensions (auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  const effectiveTransitionProps = !hasBeenClosed.current

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -157,16 +157,34 @@ describe('Collapsible', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --collapsible-panel-height CSS variable on panel', () => {
+ it('pins --collapsible-panel-height/width while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the vars) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned dimensions once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel dimensions so
+ // it flows naturally with its content.
  renderCollapsible({ defaultOpen: true });
  const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
- });
-
- it('sets --collapsible-panel-width CSS variable on panel', () => {
- renderCollapsible({ defaultOpen: true });
- const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ const style = panel.getAttribute('style') ?? '';
+ expect(style).not.toContain('--collapsible-panel-height');
+ expect(style).not.toContain('--collapsible-panel-width');
  });
  });
 

packages/headless/src/primitives/tabs/tabs-context.ts

@@ -8,7 +8,11 @@ export interface TabsContextValue {
  tabsId: string;
  registerTab: (value: string, element: HTMLElement | null) => void;
  getTabElement: (value: string) => HTMLElement | null;
- listRef: React.RefObject<HTMLElement>;
+ // The list element is tracked as state (not a ref) so the indicator, a child,
+ // re-renders once the list mounts. A child's layout effect runs before its
+ // parent's ref is attached, so a plain ref would read null on first measure.
+ listElement: HTMLElement | null;
+ setListElement: (element: HTMLElement | null) => void;
  direction: 1 | -1;
 }
 

packages/headless/src/primitives/tabs/tabs-indicator.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import type React from 'react';
-import { useEffect, useRef, useState } from 'react';
+import { useLayoutEffect, useRef, useState } from 'react';
 
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
 import { useTabsContext } from './tabs-context';
@@ -10,7 +10,7 @@ export type TabsIndicatorProps = ComponentProps<'span'>;
 
 export function TabsIndicator(props: TabsIndicatorProps) {
  const { render, ...otherProps } = props;
- const { value, getTabElement, orientation, listRef } = useTabsContext();
+ const { value, getTabElement, orientation, listElement } = useTabsContext();
 
  const [style, setStyle] = useState<React.CSSProperties>({});
  const previousRectRef = useRef<{
@@ -20,9 +20,11 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  height: number;
  } | null>(null);
 
- useEffect(() => {
+ // Measure synchronously before paint so the indicator never commits a frame
+ // at a stale position when the active tab changes.
+ useLayoutEffect(() => {
  const el = getTabElement(value);
- const list = listRef.current;
+ const list = listElement;
  if (!el || !list) {
  return;
  }
@@ -64,7 +66,7 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  ro.observe(el);
  ro.observe(list);
  return () => ro.disconnect();
- }, [value, getTabElement, orientation, listRef]);
+ }, [value, getTabElement, orientation, listElement]);
 
  const defaultProps = {
  'data-cl-slot': 'tabs-indicator',

packages/headless/src/primitives/tabs/tabs-list.tsx

@@ -10,11 +10,11 @@ export type TabsListProps = ComponentProps<'div'>;
 
 export function TabsList(props: TabsListProps) {
  const { render, children, ...otherProps } = props;
- const { orientation, listRef } = useTabsContext();
+ const { orientation, setListElement } = useTabsContext();
 
  return (
  <Composite
- ref={listRef}
+ ref={setListElement}
  orientation={orientation}
  render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
  const defaultProps: Record<string, unknown> = {

packages/headless/src/primitives/tabs/tabs-root.tsx

@@ -23,7 +23,7 @@ export function TabsRoot(props: TabsProps) {
  const tabsId = useId();
  const tabElementsRef = useRef<Map<string, HTMLElement>>(new Map());
  const tabOrderRef = useRef<string[]>([]);
- const listRef = useRef<HTMLElement>(null);
+ const [listElement, setListElement] = useState<HTMLElement | null>(null);
  const valueRef = useRef(value);
  valueRef.current = value;
 
@@ -64,10 +64,11 @@ export function TabsRoot(props: TabsProps) {
  tabsId,
  registerTab,
  getTabElement,
- listRef,
+ listElement,
+ setListElement,
  direction,
  }),
- [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, direction],
+ [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, listElement, direction],
  );
 
  return <TabsContext.Provider value={contextValue}>{children}</TabsContext.Provider>;

packages/headless/src/utils/index.ts

@@ -1,2 +1,3 @@
 export { cssVars } from './css-vars';
+export { resetLayoutStyles } from './reset-layout-styles';
 export { type ComponentProps, type DefaultProps, mergeProps, type RenderProp, renderElement } from './render-element';

packages/headless/src/utils/reset-layout-styles.ts

@@ -0,0 +1,51 @@
+/**
+ * Temporarily forces flex/grid alignment properties to `initial` so the
+ * element's content height can be measured accurately.
+ *
+ * When a panel uses `display: flex` or `display: grid` with a non-default
+ * `justify-content` / `align-items` / `align-content` / `justify-items`, the
+ * alignment can make `scrollHeight`/`scrollWidth` report a value smaller than
+ * the true content size. Resetting these to `initial` before measuring avoids
+ * that distortion.
+ *
+ * The original inline values are restored on the next animation frame so the
+ * forced-initial layout never flashes. The returned cleanup cancels that
+ * scheduled restore and reapplies the original values immediately — call it
+ * from the effect cleanup so a re-run before the frame fires doesn't leak the
+ * forced styles.
+ *
+ * @param element - The element being measured.
+ * @returns A cleanup function that cancels the scheduled restore and restores
+ * the original inline layout styles immediately.
+ */
+export function resetLayoutStyles(element: HTMLElement): () => void {
+ // Capture the value AND its priority flag so an inline `!important` is
+ // restored faithfully (getPropertyValue alone would drop the priority).
+ const keys = ['justify-content', 'align-items', 'align-content', 'justify-items'];
+ const originalLayoutStyles = keys.map(key => ({
+ key,
+ value: element.style.getPropertyValue(key),
+ priority: element.style.getPropertyPriority(key),
+ }));
+
+ keys.forEach(key => {
+ element.style.setProperty(key, 'initial', 'important');
+ });
+
+ function restore() {
+ for (const { key, value, priority } of originalLayoutStyles) {
+ if (value === '') {
+ element.style.removeProperty(key);
+ continue;
+ }
+ element.style.setProperty(key, value, priority);
+ }
+ }
+
+ const frame = requestAnimationFrame(restore);
+
+ return () => {
+ cancelAnimationFrame(frame);
+ restore();
+ };
+}

.changeset/headless-measurement-gaps.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/accordion/accordion-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useAccordionItemContext } from './accordion-context';
 
 export type AccordionPanelProps = ComponentProps<'div'>;
@@ -27,11 +29,13 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  // Measure the content height and keep it in sync via ResizeObserver
  useLayoutEffect(() => {
  if (!mounted) {
@@ -43,8 +47,12 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  return;
  }
 
- // Measure scrollHeight of the panel's content
+ // Measure scrollHeight of the panel's content. Reset flex/grid alignment
+ // first so non-default alignment can't shrink the reported height.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  };
 
@@ -54,9 +62,36 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  // Observe children mutations that affect height
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel height so the
+ // panel flows naturally with its content (CSS var omitted → height: auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => setHeight(undefined));
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to a measured pixel value when closing starts so the exit
+ // transition animates from a concrete height (height: auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  // Skip enter animation for panels that have never been closed

packages/headless/src/primitives/accordion/accordion.test.tsx

@@ -209,11 +209,31 @@ describe('Accordion', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --cl-accordion-panel-height CSS variable on panel', () => {
+ it('pins --cl-accordion-panel-height while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the var) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderAccordion({ defaultValue: ['item1'] });
+ const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned height once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel height so it
+ // flows naturally with its content.
  renderAccordion({ defaultValue: ['item1'] });
  const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
- // Verify the CSS variable is present in the style attribute
- expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ expect(panel.getAttribute('style') ?? '').not.toContain('--cl-accordion-panel-height');
  });
  });
 

packages/headless/src/primitives/collapsible/collapsible-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useCollapsibleContext } from './collapsible-context';
 
 export type CollapsiblePanelProps = ComponentProps<'div'>;
@@ -26,11 +28,13 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  useLayoutEffect(() => {
  if (!mounted) {
  return;
@@ -41,7 +45,12 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  return;
  }
 
+ // Reset flex/grid alignment before measuring so non-default alignment
+ // can't shrink the reported scroll dimensions.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  setWidth(panel.scrollWidth);
  };
@@ -51,9 +60,40 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  const ro = new ResizeObserver(measure);
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel dimensions so the
+ // panel flows naturally with its content (CSS vars omitted → auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => {
+ setHeight(undefined);
+ setWidth(undefined);
+ });
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to measured pixel values when closing starts so the exit
+ // transition animates from concrete dimensions (auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  const effectiveTransitionProps = !hasBeenClosed.current

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -157,16 +157,34 @@ describe('Collapsible', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --collapsible-panel-height CSS variable on panel', () => {
+ it('pins --collapsible-panel-height/width while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the vars) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned dimensions once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel dimensions so
+ // it flows naturally with its content.
  renderCollapsible({ defaultOpen: true });
  const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
- });
-
- it('sets --collapsible-panel-width CSS variable on panel', () => {
- renderCollapsible({ defaultOpen: true });
- const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ const style = panel.getAttribute('style') ?? '';
+ expect(style).not.toContain('--collapsible-panel-height');
+ expect(style).not.toContain('--collapsible-panel-width');
  });
  });
 

packages/headless/src/primitives/tabs/tabs-context.ts

@@ -8,7 +8,11 @@ export interface TabsContextValue {
  tabsId: string;
  registerTab: (value: string, element: HTMLElement | null) => void;
  getTabElement: (value: string) => HTMLElement | null;
- listRef: React.RefObject<HTMLElement>;
+ // The list element is tracked as state (not a ref) so the indicator, a child,
+ // re-renders once the list mounts. A child's layout effect runs before its
+ // parent's ref is attached, so a plain ref would read null on first measure.
+ listElement: HTMLElement | null;
+ setListElement: (element: HTMLElement | null) => void;
  direction: 1 | -1;
 }
 

packages/headless/src/primitives/tabs/tabs-indicator.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import type React from 'react';
-import { useEffect, useRef, useState } from 'react';
+import { useLayoutEffect, useRef, useState } from 'react';
 
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
 import { useTabsContext } from './tabs-context';
@@ -10,7 +10,7 @@ export type TabsIndicatorProps = ComponentProps<'span'>;
 
 export function TabsIndicator(props: TabsIndicatorProps) {
  const { render, ...otherProps } = props;
- const { value, getTabElement, orientation, listRef } = useTabsContext();
+ const { value, getTabElement, orientation, listElement } = useTabsContext();
 
  const [style, setStyle] = useState<React.CSSProperties>({});
  const previousRectRef = useRef<{
@@ -20,9 +20,11 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  height: number;
  } | null>(null);
 
- useEffect(() => {
+ // Measure synchronously before paint so the indicator never commits a frame
+ // at a stale position when the active tab changes.
+ useLayoutEffect(() => {
  const el = getTabElement(value);
- const list = listRef.current;
+ const list = listElement;
  if (!el || !list) {
  return;
  }
@@ -64,7 +66,7 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  ro.observe(el);
  ro.observe(list);
  return () => ro.disconnect();
- }, [value, getTabElement, orientation, listRef]);
+ }, [value, getTabElement, orientation, listElement]);
 
  const defaultProps = {
  'data-cl-slot': 'tabs-indicator',

packages/headless/src/primitives/tabs/tabs-list.tsx

@@ -10,11 +10,11 @@ export type TabsListProps = ComponentProps<'div'>;
 
 export function TabsList(props: TabsListProps) {
  const { render, children, ...otherProps } = props;
- const { orientation, listRef } = useTabsContext();
+ const { orientation, setListElement } = useTabsContext();
 
  return (
  <Composite
- ref={listRef}
+ ref={setListElement}
  orientation={orientation}
  render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
  const defaultProps: Record<string, unknown> = {

packages/headless/src/primitives/tabs/tabs-root.tsx

@@ -23,7 +23,7 @@ export function TabsRoot(props: TabsProps) {
  const tabsId = useId();
  const tabElementsRef = useRef<Map<string, HTMLElement>>(new Map());
  const tabOrderRef = useRef<string[]>([]);
- const listRef = useRef<HTMLElement>(null);
+ const [listElement, setListElement] = useState<HTMLElement | null>(null);
  const valueRef = useRef(value);
  valueRef.current = value;
 
@@ -64,10 +64,11 @@ export function TabsRoot(props: TabsProps) {
  tabsId,
  registerTab,
  getTabElement,
- listRef,
+ listElement,
+ setListElement,
  direction,
  }),
- [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, direction],
+ [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, listElement, direction],
  );
 
  return <TabsContext.Provider value={contextValue}>{children}</TabsContext.Provider>;

packages/headless/src/utils/index.ts

@@ -1,2 +1,3 @@
 export { cssVars } from './css-vars';
+export { resetLayoutStyles } from './reset-layout-styles';
 export { type ComponentProps, type DefaultProps, mergeProps, type RenderProp, renderElement } from './render-element';

packages/headless/src/utils/reset-layout-styles.ts

@@ -0,0 +1,51 @@
+/**
+ * Temporarily forces flex/grid alignment properties to `initial` so the
+ * element's content height can be measured accurately.
+ *
+ * When a panel uses `display: flex` or `display: grid` with a non-default
+ * `justify-content` / `align-items` / `align-content` / `justify-items`, the
+ * alignment can make `scrollHeight`/`scrollWidth` report a value smaller than
+ * the true content size. Resetting these to `initial` before measuring avoids
+ * that distortion.
+ *
+ * The original inline values are restored on the next animation frame so the
+ * forced-initial layout never flashes. The returned cleanup cancels that
+ * scheduled restore and reapplies the original values immediately — call it
+ * from the effect cleanup so a re-run before the frame fires doesn't leak the
+ * forced styles.
+ *
+ * @param element - The element being measured.
+ * @returns A cleanup function that cancels the scheduled restore and restores
+ * the original inline layout styles immediately.
+ */
+export function resetLayoutStyles(element: HTMLElement): () => void {
+ // Capture the value AND its priority flag so an inline `!important` is
+ // restored faithfully (getPropertyValue alone would drop the priority).
+ const keys = ['justify-content', 'align-items', 'align-content', 'justify-items'];
+ const originalLayoutStyles = keys.map(key => ({
+ key,
+ value: element.style.getPropertyValue(key),
+ priority: element.style.getPropertyPriority(key),
+ }));
+
+ keys.forEach(key => {
+ element.style.setProperty(key, 'initial', 'important');
+ });
+
+ function restore() {
+ for (const { key, value, priority } of originalLayoutStyles) {
+ if (value === '') {
+ element.style.removeProperty(key);
+ continue;
+ }
+ element.style.setProperty(key, value, priority);
+ }
+ }
+
+ const frame = requestAnimationFrame(restore);
+
+ return () => {
+ cancelAnimationFrame(frame);
+ restore();
+ };
+}

.changeset/headless-measurement-gaps.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/accordion/accordion-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useAccordionItemContext } from './accordion-context';
 
 export type AccordionPanelProps = ComponentProps<'div'>;
@@ -27,11 +29,13 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  // Measure the content height and keep it in sync via ResizeObserver
  useLayoutEffect(() => {
  if (!mounted) {
@@ -43,8 +47,12 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  return;
  }
 
- // Measure scrollHeight of the panel's content
+ // Measure scrollHeight of the panel's content. Reset flex/grid alignment
+ // first so non-default alignment can't shrink the reported height.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  };
 
@@ -54,9 +62,36 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  // Observe children mutations that affect height
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel height so the
+ // panel flows naturally with its content (CSS var omitted → height: auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => setHeight(undefined));
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to a measured pixel value when closing starts so the exit
+ // transition animates from a concrete height (height: auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  // Skip enter animation for panels that have never been closed

packages/headless/src/primitives/accordion/accordion.test.tsx

@@ -209,11 +209,31 @@ describe('Accordion', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --cl-accordion-panel-height CSS variable on panel', () => {
+ it('pins --cl-accordion-panel-height while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the var) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderAccordion({ defaultValue: ['item1'] });
+ const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned height once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel height so it
+ // flows naturally with its content.
  renderAccordion({ defaultValue: ['item1'] });
  const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
- // Verify the CSS variable is present in the style attribute
- expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ expect(panel.getAttribute('style') ?? '').not.toContain('--cl-accordion-panel-height');
  });
  });
 

packages/headless/src/primitives/collapsible/collapsible-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useCollapsibleContext } from './collapsible-context';
 
 export type CollapsiblePanelProps = ComponentProps<'div'>;
@@ -26,11 +28,13 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  useLayoutEffect(() => {
  if (!mounted) {
  return;
@@ -41,7 +45,12 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  return;
  }
 
+ // Reset flex/grid alignment before measuring so non-default alignment
+ // can't shrink the reported scroll dimensions.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  setWidth(panel.scrollWidth);
  };
@@ -51,9 +60,40 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  const ro = new ResizeObserver(measure);
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel dimensions so the
+ // panel flows naturally with its content (CSS vars omitted → auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => {
+ setHeight(undefined);
+ setWidth(undefined);
+ });
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to measured pixel values when closing starts so the exit
+ // transition animates from concrete dimensions (auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  const effectiveTransitionProps = !hasBeenClosed.current

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -157,16 +157,34 @@ describe('Collapsible', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --collapsible-panel-height CSS variable on panel', () => {
+ it('pins --collapsible-panel-height/width while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the vars) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned dimensions once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel dimensions so
+ // it flows naturally with its content.
  renderCollapsible({ defaultOpen: true });
  const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
- });
-
- it('sets --collapsible-panel-width CSS variable on panel', () => {
- renderCollapsible({ defaultOpen: true });
- const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ const style = panel.getAttribute('style') ?? '';
+ expect(style).not.toContain('--collapsible-panel-height');
+ expect(style).not.toContain('--collapsible-panel-width');
  });
  });
 

packages/headless/src/primitives/tabs/tabs-context.ts

@@ -8,7 +8,11 @@ export interface TabsContextValue {
  tabsId: string;
  registerTab: (value: string, element: HTMLElement | null) => void;
  getTabElement: (value: string) => HTMLElement | null;
- listRef: React.RefObject<HTMLElement>;
+ // The list element is tracked as state (not a ref) so the indicator, a child,
+ // re-renders once the list mounts. A child's layout effect runs before its
+ // parent's ref is attached, so a plain ref would read null on first measure.
+ listElement: HTMLElement | null;
+ setListElement: (element: HTMLElement | null) => void;
  direction: 1 | -1;
 }
 

packages/headless/src/primitives/tabs/tabs-indicator.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import type React from 'react';
-import { useEffect, useRef, useState } from 'react';
+import { useLayoutEffect, useRef, useState } from 'react';
 
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
 import { useTabsContext } from './tabs-context';
@@ -10,7 +10,7 @@ export type TabsIndicatorProps = ComponentProps<'span'>;
 
 export function TabsIndicator(props: TabsIndicatorProps) {
  const { render, ...otherProps } = props;
- const { value, getTabElement, orientation, listRef } = useTabsContext();
+ const { value, getTabElement, orientation, listElement } = useTabsContext();
 
  const [style, setStyle] = useState<React.CSSProperties>({});
  const previousRectRef = useRef<{
@@ -20,9 +20,11 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  height: number;
  } | null>(null);
 
- useEffect(() => {
+ // Measure synchronously before paint so the indicator never commits a frame
+ // at a stale position when the active tab changes.
+ useLayoutEffect(() => {
  const el = getTabElement(value);
- const list = listRef.current;
+ const list = listElement;
  if (!el || !list) {
  return;
  }
@@ -64,7 +66,7 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  ro.observe(el);
  ro.observe(list);
  return () => ro.disconnect();
- }, [value, getTabElement, orientation, listRef]);
+ }, [value, getTabElement, orientation, listElement]);
 
  const defaultProps = {
  'data-cl-slot': 'tabs-indicator',

packages/headless/src/primitives/tabs/tabs-list.tsx

@@ -10,11 +10,11 @@ export type TabsListProps = ComponentProps<'div'>;
 
 export function TabsList(props: TabsListProps) {
  const { render, children, ...otherProps } = props;
- const { orientation, listRef } = useTabsContext();
+ const { orientation, setListElement } = useTabsContext();
 
  return (
  <Composite
- ref={listRef}
+ ref={setListElement}
  orientation={orientation}
  render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
  const defaultProps: Record<string, unknown> = {

packages/headless/src/primitives/tabs/tabs-root.tsx

@@ -23,7 +23,7 @@ export function TabsRoot(props: TabsProps) {
  const tabsId = useId();
  const tabElementsRef = useRef<Map<string, HTMLElement>>(new Map());
  const tabOrderRef = useRef<string[]>([]);
- const listRef = useRef<HTMLElement>(null);
+ const [listElement, setListElement] = useState<HTMLElement | null>(null);
  const valueRef = useRef(value);
  valueRef.current = value;
 
@@ -64,10 +64,11 @@ export function TabsRoot(props: TabsProps) {
  tabsId,
  registerTab,
  getTabElement,
- listRef,
+ listElement,
+ setListElement,
  direction,
  }),
- [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, direction],
+ [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, listElement, direction],
  );
 
  return <TabsContext.Provider value={contextValue}>{children}</TabsContext.Provider>;

packages/headless/src/utils/index.ts

@@ -1,2 +1,3 @@
 export { cssVars } from './css-vars';
+export { resetLayoutStyles } from './reset-layout-styles';
 export { type ComponentProps, type DefaultProps, mergeProps, type RenderProp, renderElement } from './render-element';

packages/headless/src/utils/reset-layout-styles.ts

@@ -0,0 +1,51 @@
+/**
+ * Temporarily forces flex/grid alignment properties to `initial` so the
+ * element's content height can be measured accurately.
+ *
+ * When a panel uses `display: flex` or `display: grid` with a non-default
+ * `justify-content` / `align-items` / `align-content` / `justify-items`, the
+ * alignment can make `scrollHeight`/`scrollWidth` report a value smaller than
+ * the true content size. Resetting these to `initial` before measuring avoids
+ * that distortion.
+ *
+ * The original inline values are restored on the next animation frame so the
+ * forced-initial layout never flashes. The returned cleanup cancels that
+ * scheduled restore and reapplies the original values immediately — call it
+ * from the effect cleanup so a re-run before the frame fires doesn't leak the
+ * forced styles.
+ *
+ * @param element - The element being measured.
+ * @returns A cleanup function that cancels the scheduled restore and restores
+ * the original inline layout styles immediately.
+ */
+export function resetLayoutStyles(element: HTMLElement): () => void {
+ // Capture the value AND its priority flag so an inline `!important` is
+ // restored faithfully (getPropertyValue alone would drop the priority).
+ const keys = ['justify-content', 'align-items', 'align-content', 'justify-items'];
+ const originalLayoutStyles = keys.map(key => ({
+ key,
+ value: element.style.getPropertyValue(key),
+ priority: element.style.getPropertyPriority(key),
+ }));
+
+ keys.forEach(key => {
+ element.style.setProperty(key, 'initial', 'important');
+ });
+
+ function restore() {
+ for (const { key, value, priority } of originalLayoutStyles) {
+ if (value === '') {
+ element.style.removeProperty(key);
+ continue;
+ }
+ element.style.setProperty(key, value, priority);
+ }
+ }
+
+ const frame = requestAnimationFrame(restore);
+
+ return () => {
+ cancelAnimationFrame(frame);
+ restore();
+ };
+}

.changeset/headless-measurement-gaps.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/accordion/accordion-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useAccordionItemContext } from './accordion-context';
 
 export type AccordionPanelProps = ComponentProps<'div'>;
@@ -27,11 +29,13 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  // Measure the content height and keep it in sync via ResizeObserver
  useLayoutEffect(() => {
  if (!mounted) {
@@ -43,8 +47,12 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  return;
  }
 
- // Measure scrollHeight of the panel's content
+ // Measure scrollHeight of the panel's content. Reset flex/grid alignment
+ // first so non-default alignment can't shrink the reported height.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  };
 
@@ -54,9 +62,36 @@ export const AccordionPanel = React.forwardRef<HTMLDivElement, AccordionPanelPro
  // Observe children mutations that affect height
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel height so the
+ // panel flows naturally with its content (CSS var omitted → height: auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => setHeight(undefined));
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to a measured pixel value when closing starts so the exit
+ // transition animates from a concrete height (height: auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  // Skip enter animation for panels that have never been closed

packages/headless/src/primitives/accordion/accordion.test.tsx

@@ -209,11 +209,31 @@ describe('Accordion', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --cl-accordion-panel-height CSS variable on panel', () => {
+ it('pins --cl-accordion-panel-height while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the var) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderAccordion({ defaultValue: ['item1'] });
+ const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned height once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel height so it
+ // flows naturally with its content.
  renderAccordion({ defaultValue: ['item1'] });
  const panel = document.querySelector('[data-cl-slot="accordion-panel"]') as HTMLElement;
- // Verify the CSS variable is present in the style attribute
- expect(panel.getAttribute('style')).toContain('--cl-accordion-panel-height');
+ expect(panel.getAttribute('style') ?? '').not.toContain('--cl-accordion-panel-height');
  });
  });
 

packages/headless/src/primitives/collapsible/collapsible-panel.tsx

@@ -3,8 +3,10 @@
 import { useMergeRefs } from '@floating-ui/react';
 import React, { type RefObject, useLayoutEffect, useRef, useState } from 'react';
 
+import { useAnimationsFinished } from '../../hooks/use-animations-finished';
 import { useTransition } from '../../hooks/use-transition';
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { resetLayoutStyles } from '../../utils/reset-layout-styles';
 import { useCollapsibleContext } from './collapsible-context';
 
 export type CollapsiblePanelProps = ComponentProps<'div'>;
@@ -26,11 +28,13 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  hasBeenClosed.current = true;
  }
 
- const { mounted, transitionProps } = useTransition({
+ const { mounted, transitionStatus, transitionProps } = useTransition({
  open,
  ref: panelRef as RefObject<HTMLElement>,
  });
 
+ const runOnAnimationsFinished = useAnimationsFinished(panelRef, open);
+
  useLayoutEffect(() => {
  if (!mounted) {
  return;
@@ -41,7 +45,12 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  return;
  }
 
+ // Reset flex/grid alignment before measuring so non-default alignment
+ // can't shrink the reported scroll dimensions.
+ let restoreLayoutStyles: (() => void) | undefined;
  const measure = () => {
+ restoreLayoutStyles?.();
+ restoreLayoutStyles = resetLayoutStyles(panel);
  setHeight(panel.scrollHeight);
  setWidth(panel.scrollWidth);
  };
@@ -51,9 +60,40 @@ export const CollapsiblePanel = React.forwardRef<HTMLDivElement, CollapsiblePane
  const ro = new ResizeObserver(measure);
  ro.observe(panel, { box: 'border-box' });
 
- return () => ro.disconnect();
+ return () => {
+ ro.disconnect();
+ restoreLayoutStyles?.();
+ };
  }, [mounted]);
 
+ // Once the open animation settles, drop the measured pixel dimensions so the
+ // panel flows naturally with its content (CSS vars omitted → auto).
+ useLayoutEffect(() => {
+ if (!open || !mounted) {
+ return;
+ }
+ runOnAnimationsFinished(() => {
+ setHeight(undefined);
+ setWidth(undefined);
+ });
+ }, [open, mounted, runOnAnimationsFinished]);
+
+ // Re-pin to measured pixel values when closing starts so the exit
+ // transition animates from concrete dimensions (auto can't interpolate).
+ useLayoutEffect(() => {
+ if (open || transitionStatus !== 'ending') {
+ return;
+ }
+ const panel = panelRef.current;
+ if (!panel) {
+ return;
+ }
+ const restoreLayoutStyles = resetLayoutStyles(panel);
+ setHeight(panel.scrollHeight);
+ setWidth(panel.scrollWidth);
+ return restoreLayoutStyles;
+ }, [open, transitionStatus]);
+
  const state = { open };
 
  const effectiveTransitionProps = !hasBeenClosed.current

packages/headless/src/primitives/collapsible/collapsible.test.tsx

@@ -157,16 +157,34 @@ describe('Collapsible', () => {
  expect(panel).not.toHaveAttribute('data-cl-starting-style');
  });
 
- it('sets --collapsible-panel-height CSS variable on panel', () => {
+ it('pins --collapsible-panel-height/width while the open animation is in progress', () => {
+ // Keep an animation pending so the idle reset (which clears the vars) holds off.
+ const original = (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = () => [
+ { finished: new Promise<void>(() => {}) },
+ ];
+ try {
+ renderCollapsible({ defaultOpen: true });
+ const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
+ expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ } finally {
+ if (original) {
+ (Element.prototype as { getAnimations?: unknown }).getAnimations = original;
+ } else {
+ delete (Element.prototype as { getAnimations?: unknown }).getAnimations;
+ }
+ }
+ });
+
+ it('clears the pinned dimensions once the panel settles open (flows at auto)', () => {
+ // With no running animations the panel drops the measured pixel dimensions so
+ // it flows naturally with its content.
  renderCollapsible({ defaultOpen: true });
  const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-height');
- });
-
- it('sets --collapsible-panel-width CSS variable on panel', () => {
- renderCollapsible({ defaultOpen: true });
- const panel = document.querySelector('[data-cl-slot="collapsible-panel"]') as HTMLElement;
- expect(panel.getAttribute('style')).toContain('--collapsible-panel-width');
+ const style = panel.getAttribute('style') ?? '';
+ expect(style).not.toContain('--collapsible-panel-height');
+ expect(style).not.toContain('--collapsible-panel-width');
  });
  });
 

packages/headless/src/primitives/tabs/tabs-context.ts

@@ -8,7 +8,11 @@ export interface TabsContextValue {
  tabsId: string;
  registerTab: (value: string, element: HTMLElement | null) => void;
  getTabElement: (value: string) => HTMLElement | null;
- listRef: React.RefObject<HTMLElement>;
+ // The list element is tracked as state (not a ref) so the indicator, a child,
+ // re-renders once the list mounts. A child's layout effect runs before its
+ // parent's ref is attached, so a plain ref would read null on first measure.
+ listElement: HTMLElement | null;
+ setListElement: (element: HTMLElement | null) => void;
  direction: 1 | -1;
 }
 

packages/headless/src/primitives/tabs/tabs-indicator.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import type React from 'react';
-import { useEffect, useRef, useState } from 'react';
+import { useLayoutEffect, useRef, useState } from 'react';
 
 import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
 import { useTabsContext } from './tabs-context';
@@ -10,7 +10,7 @@ export type TabsIndicatorProps = ComponentProps<'span'>;
 
 export function TabsIndicator(props: TabsIndicatorProps) {
  const { render, ...otherProps } = props;
- const { value, getTabElement, orientation, listRef } = useTabsContext();
+ const { value, getTabElement, orientation, listElement } = useTabsContext();
 
  const [style, setStyle] = useState<React.CSSProperties>({});
  const previousRectRef = useRef<{
@@ -20,9 +20,11 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  height: number;
  } | null>(null);
 
- useEffect(() => {
+ // Measure synchronously before paint so the indicator never commits a frame
+ // at a stale position when the active tab changes.
+ useLayoutEffect(() => {
  const el = getTabElement(value);
- const list = listRef.current;
+ const list = listElement;
  if (!el || !list) {
  return;
  }
@@ -64,7 +66,7 @@ export function TabsIndicator(props: TabsIndicatorProps) {
  ro.observe(el);
  ro.observe(list);
  return () => ro.disconnect();
- }, [value, getTabElement, orientation, listRef]);
+ }, [value, getTabElement, orientation, listElement]);
 
  const defaultProps = {
  'data-cl-slot': 'tabs-indicator',

packages/headless/src/primitives/tabs/tabs-list.tsx

@@ -10,11 +10,11 @@ export type TabsListProps = ComponentProps<'div'>;
 
 export function TabsList(props: TabsListProps) {
  const { render, children, ...otherProps } = props;
- const { orientation, listRef } = useTabsContext();
+ const { orientation, setListElement } = useTabsContext();
 
  return (
  <Composite
- ref={listRef}
+ ref={setListElement}
  orientation={orientation}
  render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
  const defaultProps: Record<string, unknown> = {

packages/headless/src/primitives/tabs/tabs-root.tsx

@@ -23,7 +23,7 @@ export function TabsRoot(props: TabsProps) {
  const tabsId = useId();
  const tabElementsRef = useRef<Map<string, HTMLElement>>(new Map());
  const tabOrderRef = useRef<string[]>([]);
- const listRef = useRef<HTMLElement>(null);
+ const [listElement, setListElement] = useState<HTMLElement | null>(null);
  const valueRef = useRef(value);
  valueRef.current = value;
 
@@ -64,10 +64,11 @@ export function TabsRoot(props: TabsProps) {
  tabsId,
  registerTab,
  getTabElement,
- listRef,
+ listElement,
+ setListElement,
  direction,
  }),
- [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, direction],
+ [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, listElement, direction],
  );
 
  return <TabsContext.Provider value={contextValue}>{children}</TabsContext.Provider>;

packages/headless/src/utils/index.ts

@@ -1,2 +1,3 @@
 export { cssVars } from './css-vars';
+export { resetLayoutStyles } from './reset-layout-styles';
 export { type ComponentProps, type DefaultProps, mergeProps, type RenderProp, renderElement } from './render-element';

packages/headless/src/utils/reset-layout-styles.ts

@@ -0,0 +1,51 @@
+/**
+ * Temporarily forces flex/grid alignment properties to `initial` so the
+ * element's content height can be measured accurately.
+ *
+ * When a panel uses `display: flex` or `display: grid` with a non-default
+ * `justify-content` / `align-items` / `align-content` / `justify-items`, the
+ * alignment can make `scrollHeight`/`scrollWidth` report a value smaller than
+ * the true content size. Resetting these to `initial` before measuring avoids
+ * that distortion.
+ *
+ * The original inline values are restored on the next animation frame so the
+ * forced-initial layout never flashes. The returned cleanup cancels that
+ * scheduled restore and reapplies the original values immediately — call it
+ * from the effect cleanup so a re-run before the frame fires doesn't leak the
+ * forced styles.
+ *
+ * @param element - The element being measured.
+ * @returns A cleanup function that cancels the scheduled restore and restores
+ * the original inline layout styles immediately.
+ */
+export function resetLayoutStyles(element: HTMLElement): () => void {
+ // Capture the value AND its priority flag so an inline `!important` is
+ // restored faithfully (getPropertyValue alone would drop the priority).
+ const keys = ['justify-content', 'align-items', 'align-content', 'justify-items'];
+ const originalLayoutStyles = keys.map(key => ({
+ key,
+ value: element.style.getPropertyValue(key),
+ priority: element.style.getPropertyPriority(key),
+ }));
+
+ keys.forEach(key => {
+ element.style.setProperty(key, 'initial', 'important');
+ });
+
+ function restore() {
+ for (const { key, value, priority } of originalLayoutStyles) {
+ if (value === '') {
+ element.style.removeProperty(key);
+ continue;
+ }
+ element.style.setProperty(key, value, priority);
+ }
+ }
+
+ const frame = requestAnimationFrame(restore);
+
+ return () => {
+ cancelAnimationFrame(frame);
+ restore();
+ };
+}