Skip to content

[scroll area] Add overflow presence state attributes and CSS variables #2478

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Sep 18, 2025
Merged

[scroll area] Add overflow presence state attributes and CSS variables #2478

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
51392ce
[scroll area] Overflow presence state attributes
atomiks Aug 9, 2025
cc37b73
Merge branch 'master' into feat/scroll-area-overflow-presence
atomiks Sep 17, 2025
3940537
lint
atomiks Sep 17, 2025
b1effeb
feat: thresholds, css vars
atomiks Sep 17, 2025
6aeb302
docs: fix anatomy
atomiks Sep 17, 2025
35109fa
lint
atomiks Sep 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 42 additions & 1 deletion docs/reference/generated/scroll-area-root.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,12 @@
"name": "ScrollAreaRoot",
"description": "Groups all parts of the scroll area.\nRenders a `<div>` element.",
"props": {
"overflowEdgeThreshold": {
"type": "number | Partial<{ xStart: number, xEnd: number, yStart: number, yEnd: number }>",
"default": "0",
"description": "The threshold in pixels that must be passed before the overflow edge attributes are applied.\nAccepts a single number for all edges or an object to configure them individually.",
"detailedType": "| number\n| {\n xStart?: number\n xEnd?: number\n yStart?: number\n yEnd?: number\n }\n| undefined"
},
"className": {
"type": "string | ((state: ScrollArea.Root.State) => string)",
"description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
Expand All @@ -12,7 +18,26 @@
"detailedType": "| ReactElement\n| ((\n props: HTMLProps,\n state: ScrollArea.Root.State,\n ) => ReactElement)"
}
},
"dataAttributes": {},
"dataAttributes": {
"data-has-overflow-x": {
"description": "Present when the scroll area content is wider than the viewport."
},
"data-has-overflow-y": {
"description": "Present when the scroll area content is taller than the viewport."
},
"data-overflow-x-end": {
Copy link
Member

@michaldudak michaldudak Sep 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the advantage of having separate attributes for -start and -end?
We could use data-has-overflow-x="start end".

Copy link
Contributor Author

@atomiks atomiks Sep 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Edge scroll gradients work better with boolean attrs.

Compare:

.fade-start[data-overflow-y-start],
.fade-end[data-overflow-y-end] {
  opacity: 1;
}

This breaks unless you use ~= token matchers which isn't intuitive:

.fade-start[data-has-overflow-y="start"],
.fade-end[data-has-overflow-y="end"] {
  opacity: 1;
}

"description": "Present when there is overflow on the horizontal end side."
},
"data-overflow-x-start": {
"description": "Present when there is overflow on the horizontal start side."
},
"data-overflow-y-end": {
"description": "Present when there is overflow on the vertical end side."
},
"data-overflow-y-start": {
"description": "Present when there is overflow on the vertical start side."
}
},
"cssVariables": {
"--scroll-area-corner-height": {
"description": "The scroll area's corner height.",
Expand All @@ -21,6 +46,22 @@
"--scroll-area-corner-width": {
"description": "The scroll area's corner width.",
"type": "number"
},
"--scroll-area-overflow-x-end": {
"description": "The distance from the horizontal end edge in pixels.",
"type": "number"
},
"--scroll-area-overflow-x-start": {
"description": "The distance from the horizontal start edge in pixels.",
"type": "number"
},
"--scroll-area-overflow-y-end": {
"description": "The distance from the vertical end edge in pixels.",
"type": "number"
},
"--scroll-area-overflow-y-start": {
"description": "The distance from the vertical start edge in pixels.",
"type": "number"
}
}
}
18 changes: 18 additions & 0 deletions docs/reference/generated/scroll-area-scrollbar.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,27 @@
"description": "Indicates the orientation of the scrollbar.",
"type": "'horizontal' | 'vertical'"
},
"data-has-overflow-x": {
"description": "Present when the scroll area content is wider than the viewport."
},
"data-has-overflow-y": {
"description": "Present when the scroll area content is taller than the viewport."
},
"data-hovering": {
"description": "Present when the pointer is over the scroll area."
},
"data-overflow-x-end": {
"description": "Present when there is overflow on the horizontal end side."
},
"data-overflow-x-start": {
"description": "Present when there is overflow on the horizontal start side."
},
"data-overflow-y-end": {
"description": "Present when there is overflow on the vertical end side."
},
"data-overflow-y-start": {
"description": "Present when there is overflow on the vertical start side."
},
"data-scrolling": {
"description": "Present when the users scrolls inside the scroll area."
}
Expand Down
21 changes: 20 additions & 1 deletion docs/reference/generated/scroll-area-viewport.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,25 @@
"detailedType": "| ReactElement\n| ((\n props: HTMLProps,\n state: ScrollArea.Viewport.State,\n ) => ReactElement)"
}
},
"dataAttributes": {},
"dataAttributes": {
"data-has-overflow-x": {
"description": "Present when the scroll area content is wider than the viewport."
},
"data-has-overflow-y": {
"description": "Present when the scroll area content is taller than the viewport."
},
"data-overflow-x-end": {
"description": "Present when there is overflow on the horizontal end side."
},
"data-overflow-x-start": {
"description": "Present when there is overflow on the horizontal start side."
},
"data-overflow-y-end": {
"description": "Present when there is overflow on the vertical end side."
},
"data-overflow-y-start": {
"description": "Present when there is overflow on the vertical start side."
}
},
"cssVariables": {}
}
7 changes: 4 additions & 3 deletions docs/src/app/(private)/experiments/scroll-area/scroll-area-inset.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
import * as React from 'react';
import { ScrollArea } from '@base-ui-components/react/scroll-area';
import { DirectionProvider } from '@base-ui-components/react/direction-provider';
import styles from './scroll-area-inset.module.css';

export default function ScrollAreaInset() {
return (
<div>
<DirectionProvider direction="rtl">
<p>Scroll content is not clipped by inset scrollbars (user-defined paddings)</p>
<ScrollArea.Root className={styles.Root}>
<ScrollArea.Root className={styles.Root} style={{ direction: 'rtl' }}>
<ScrollArea.Viewport className={styles.Viewport}>
<div className={styles.Content}>
<p>
Expand All @@ -25,6 +26,6 @@ export default function ScrollAreaInset() {
</ScrollArea.Scrollbar>
<ScrollArea.Corner />
</ScrollArea.Root>
</div>
</DirectionProvider>
);
}
4 changes: 3 additions & 1 deletion docs/src/app/(public)/(content)/react/components/scroll-area/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,9 @@ Import the component and assemble its parts:
import { ScrollArea } from '@base-ui-components/react/scroll-area';

<ScrollArea.Root>
<ScrollArea.Viewport />
<ScrollArea.Viewport>
<ScrollArea.Content />
</ScrollArea.Viewport>
<ScrollArea.Scrollbar>
<ScrollArea.Thumb />
</ScrollArea.Scrollbar>
Expand Down
8 changes: 7 additions & 1 deletion packages/react/src/scroll-area/content/ScrollAreaContent.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@ import { useIsoLayoutEffect } from '@base-ui-components/utils/useIsoLayoutEffect
import type { BaseUIComponentProps } from '../../utils/types';
import { useScrollAreaViewportContext } from '../viewport/ScrollAreaViewportContext';
import { useRenderElement } from '../../utils/useRenderElement';
import { useScrollAreaRootContext } from '../root/ScrollAreaRootContext';
import { scrollAreaStateAttributesMapping } from '../root/stateAttributes';
import type { ScrollAreaRoot } from '../root/ScrollAreaRoot';

/**
* A container for the content of the scroll area.
Expand All @@ -20,6 +23,7 @@ export const ScrollAreaContent = React.forwardRef(function ScrollAreaContent(
const contentWrapperRef = React.useRef<HTMLDivElement | null>(null);

const { computeThumbPosition } = useScrollAreaViewportContext();
const { viewportState } = useScrollAreaRootContext();

useIsoLayoutEffect(() => {
if (typeof ResizeObserver === 'undefined') {
Expand All @@ -39,6 +43,8 @@ export const ScrollAreaContent = React.forwardRef(function ScrollAreaContent(

const element = useRenderElement('div', componentProps, {
ref: [forwardedRef, contentWrapperRef],
state: viewportState,
stateAttributesMapping: scrollAreaStateAttributesMapping,
props: [
{
role: 'presentation',
Expand All @@ -54,7 +60,7 @@ export const ScrollAreaContent = React.forwardRef(function ScrollAreaContent(
});

export namespace ScrollAreaContent {
export interface State {}
export interface State extends ScrollAreaRoot.State {}

export interface Props extends BaseUIComponentProps<'div', State> {}
}
Loading
Loading