[css-ui][selectors][mediaqueries] Expose current scrolling direction

A common UI pattern on the web is to hide/show or partially collapse some content based on whether the user is currently scrolling up or down. I'm not particularly fond of this UI pattern, but it is widespread and is often necessary for long pages on mobile screens.

This currently requires JavaScript scroll listeners to change a class on the body or other scroll container in order to trigger the alternate layout of the collapsible headers/footers (and that's assuming it isn't done entirely in JS-framework state propagation!)

Browser-managed scrolling direction pseudoclasses on the scroll container would eliminate the need for many JS scroll listeners. Something like body:scrolling-forward vs body:scrolling-backward for primary (block) direction scrolling, and some other logical names for cross/inline scrolling. Maybe also some way to distinguish when scrolling has stopped for a while.

Pseudoclasses could also enable browser-managed heuristics for better detecting when the scroll direction has changed (or stopped), based on the device scroll mechanism (touch gesture, keyboard, mouse wheel) or user accessibility customizations. For example, a user with shaky fingers might want to customize how much they need to scroll in a given direction before the layout shifts on them.

(I don't have the capacity to work on this; just throwing it out there in case someone else wants to pick it up!)

Because we do have both physical and logical dimensions to deal with in these scenarios, I wonder if it's worth recommending this as a functional pseudo-class that takes a direction/state of the scrolling element as a parameter?

body:scrolling(bottom) currently being scrolled toward bottom edge
body:scrolling(inline-start) currently being scrolled toward inline-start edge
body:scrolling currently being scrolled in any direction

I've found myself disabling :hover,:active, and even animation stylings depending on the user currently scrolling. The last example could help in these cases.

In general, I do wonder about some circularity when this pseudo class matches and then layout/flow changes so the scrollHeight/scrollWidth is changed in a way where the browser must manipulate the scroll position and now the pseudo class wouldn't match?

This was just mentioned as an alternative solution to #5670 :)
One shortcoming I see with an on-or-off pseudoclass is that you aren't literally scrolling out the top bar with e.g. your finger, i.e. it doesn't move with your finger as you move it up and down. It merely switches to a state once your scrolling reaches a threshold, and the best you can do as far as I can tell is give it a transition, which does not correlate to your finger movements.

Recently also came up in a discussion where an author wants to hide certain toolbars as the user scrolls down, but re-show those toolbars once they scroll back up again - a pretty common pattern which was already acknowledged as such by the WG here

A solution I was thinking of, was to use media queries.

@media (scroll-direction: block | block-start | block-end | inline | inline-start | inline-end ) { … }

Values are:

block: Scrolling in the block direction (aka to the top or bottom in a “default” ltr+toptobottom scenario)
block-start: Scrolling in the block-start direction (aka to the top in a “default” ltr+toptobottom scenario)
block-end: Scrolling in the block-start direction (aka to the bottom in a “default” ltr+toptobottom scenario)
inline: Scrolling in the inline direction (aka to the left or right in a “default” ltr+toptobottom scenario)
inline-start: Scrolling in the inline-start direction (aka to the left in a “default” ltr+toptobottom scenario)
inline-end: Scrolling in the inline-end direction (aka to the right in a “default” ltr+toptobottom scenario)

When you reach the start or end of a scroller, the values would still keep on being truthy: say you're at the bottom of the page and are overscrolling, @media (scroll-direction: block-end) would still be in effect.

By using a MQ, one could also easily nest them once css-nesting lands:

#navbar {
  position: sticky;
  top: 0;
  transition: transform 0.25s ease-in;

  /* Hide when scrolling towards the bottom */
  @media (scroll-direction: block-end) {
    transition-delay: 250ms;
    transform: translateY(-95%);
  }
}

What if the developer wants to only bring in or out a toolbar after a delay or certain number of pixels scrolled? For that reason I think an event might work better than a CSS feature in practice.

What if the developer wants to only bring in or out a toolbar after a delay

Authors can use transition-delay: 250ms; for that.

… or certain number of pixels scrolled

This would not be covered by the proposed feature, but would be something for the future scroll-triggered animations spec (not to be confused with the current scroll-linked animations spec).

I do expect implementers to include some cleverness when detecting the scroll-direction, such as using some kind of (small) threshold before triggering a direction change.

Thinking out loud here, it would be something that takes both distance and time into account. Say that the scroll-detection runs every 100ms (just grabbing a number here), it would need to check whether a certain distance THRESHOLD was scrolled, and only then do the direction.

In JS code (line 9):

const THRESHOLD = 10;
let curScrollPosition = 0, prevScrollPosition = 0;

setInterval(() => {
  // Capture current scrollPosition
  curScrollPosition = …;

  // Bail out if scrolled only for a tiny amount
  if(Math.abs(prevScrollPosition - curScrollPosition) <= THRESHOLD) return;

  // @TODO: draw rest of the owl ..
  
  // Get ready for next tick
  prevScrollPosition = curScrollPosition;
}, 100);

@jonjohnjohnson

One downside of using a media query for this is that you're just targetting the viewport with it. You can't target a different scroll container element within your page. Though maybe this could somehow be achieved with container queries as well.
A benefit of this approach is that a media query is independent of the element(s) you actually want to style. Another benefit is that authors can also use this query in JavaScript via window.matchMedia().

Regarding the pseudo-class approach, I like @jonjohnjohnson's idea of functional pseudo-classes. With those, the threshold mentioned by @chrishtr could be provided as a parameter of that function. That could then look like this:

header {
  transition: transform 0.25s ease-in;
  transform: translateY(-100%);
}

:scrolling(block-start, 20px) > header {
  transition-delay: 250ms;
  transform: translateY(0);
}

To me, both ideas seem valid solutions for the use-case provided.

Sebastian

As there are now two very different proposals, I generalized the subject and added the related labels.

Sebastian

Bikeshedding...

scroll-state(moving) / scroll-state(moving: forward)
scroll-state(moved) / scroll-state(moved: down)

Or...

scroll-state(active) / scroll-state(active: forward)
scroll-state(offset) / scroll-state(offset: down)

@mirisuzanne

@mirisuzanne scrolling / scrolled?

There are a bunch of demos I built for https://www.bram.us/2023/10/23/css-scroll-detection/ that depend only on the active scroll direction (and also scroll speed). Once you stop scrolling, the effect no longer applies.

For example:

Motion Blur Scroll: https://codepen.io/bramus/full/XWoREjv

BADASS: https://codepen.io/bramus/full/OJrxBaL

Both of these demos, and many of the others which only have an effect while scrolling also use the velocity, or at least would benefit from using the scroll velocity. This suggests to me that a scroll driven animation would better suit these use cases, e.g.

.tilt {
  animation: tilt linear both;
  animation-timeline: scroll-speed();
  /* Getting very creative with units here. */
  animation-range: -100px/s 100px/s;
}

I suspect a somewhat common use case, given sufficient delays before returning to the none state, might be to recreate overlay scrollbars (i.e. temporarily show a scrollbar thumb when there has been recent scrolling). However this is likely a bit of a usability challenge.

The “Hidey Bar” then OTOH is the typical example that depends on the last non-none scroll-direction value. In https://brm.us/hidey-bar I “remember” the last-non-none direction by (ab)using an infinite transition-delay on the custom prop that stores the direction. But it would be nice/handy if this “remember“ option were built into the API of course, since you don’t want to duplicate the scroll state query value into a custom property which you then use in the rest of your code.

The hidey bar case is an extremely common use case in the wild (typically implemented in JS), and the one for which this API was designed. We should focus on solving this use case well - for which we need to have the last scrolled direction persisted. It may be nice / handy if we had the option to handle the is actively scrolling case, however, I haven't seen too many use cases in the wild of this which aren't also velocity dependent and would need more than the scroll direction.

@flackr

+1 to @flackr. That's usually the case, so probably solving velocity will solve more cases.
If we want to persist the velocity past the scrollend point then we should probably solve transitioned progress of animations, and that might be something we can build on top of.
Here is an example of both using @bramus' custom properties trick (SDA required): https://jsbin.com/calicaxuhe/edit?css,output

Furthermore, if we solve velocity/delayed we should probably do so for pointer-driven animations as well.

Though there are use-cases where direction is used without depending on velocity. These are usually show/hide of fixedpos UI, usually on mobile. For example: show/hide scroll-to-top button or header when scrolling back up, kinda like the addressbar does it.

+1 to @flackr. That's usually the case, so probably solving velocity will solve more cases. If we want to persist the velocity past the scrollend point then we should probably solve transitioned progress of animations, and that might be something we can build on top of. Here is an example of both using @bramus' custom properties trick (SDA required): https://jsbin.com/calicaxuhe/edit?css,output

Right, solving #7059 would mean that a VelocityTimeline could be combined with this delay to implement a an effect that persists past the end.

Furthermore, if we solve velocity/delayed we should probably do so for pointer-driven animations as well.

Yes, this makes sense to me.

Though there are use-cases where direction is used without depending on velocity. These are usually show/hide of fixedpos UI, usually on mobile. For example: show/hide scroll-to-top button or header when scrolling back up, kinda like the addressbar does it.

Right, in the vast majority of these cases, developers don't want the fixed pos ui to go away when scrolling stops - otherwise it would prevent a usability nightmare.

For cases where the bar scrolls in as the user scrolls we have talked about this in #5670 where I proposed that a tweak to position sticky could work.

@container

The CSS Working Group just discussed [css-ui][selectors][mediaqueries] Expose current scrolling direction, and agreed to the following:

RESOLVED: Working on scrolling queries

The full IRC log of that discussion

<fantasai> TabAtkins: We have a whole batch of scroll-related container queries
<fantasai> TabAtkins: There are a lot of use cases in this space, particularly about knowing the last known scroll direction
<fantasai> TabAtkins: Two questions are: what's most recent scroll direction. Other is what is current scrolling direction.
<fantasai> TabAtkins: Hidey UI is like this on mobile
<fantasai> TabAtkins: Some discussion about velocity and other things that might be better to handle as scroll animations
<smfr> q+
<fantasai> TabAtkins: There's an explainer in the issue
<fantasai> smfr: In general this seems reasonable. Went through explainer, didn't see any explanation of rubber-banding
<fantasai> smfr: I don't think we want to expose that change in direction to web content
<fantasai> smfr: Also curious, what happens for scrolls that result from content changes
<fantasai> smfr: i.e. scrolls that scroll anchoring tries to prevent
<fantasai> smfr: Could end up with circularity, or oscillating between two states -- we see this often with JS-driven changes
<fantasai> TabAtkins: I think the answer should be that we base this on user-driven scrolling, so not script-driven or content-driven
<fantasai> TabAtkins: that would avoid these circularity issues
<flackr> +1
<Rossen8> ack smfr
<fantasai> TabAtkins: And it's close to impossible to detect in JS, could address directly this way
<fantasai> TabAtkins: Don't think there's a use case for script scrolling for these things
<fantasai> smfr: Seems surprising, because wouldn't an animated scroll to 0,0 want to show/hide these bars?
<fantasai> TabAtkins: possibly, but at that point you're scripting, so why not just script it
<flackr> I think at least scroll anchoring should not count, programmatic scrolling may be interesting
<fantasai> [missed]
<fantasai> Rossen8: what about autoscrolling?
<fantasai> TabAtkins: that's still scrolling
<ntim> q+
<fantasai> TabAtkins: Wanted to ask if group wants to pursue this idea
<fantasai> ntim: Not sure I'm convinced by answer that if we invoke script we can just invoke more script
<fantasai> ntim: The way you write the query is @container scroll-state(), and if you invoke script and you can't change that state, then you have to duplicate your CSS to support a class
<fantasai> ntim: And also have your scroll direction query
<fantasai> ntim: It would be duplicated into 2 places, if you invoke script to manipulate the state
<flackr> I think we can explore this with an example of how this would be done
<fantasai> TabAtkins: Question of what to do about script-driven scrolls is something to think more about, so let's discuss in the issues
<Rossen8> ack *
<Rossen8> ack ntim
<Rossen8> ack fantasai
<TabAtkins> fantasai: you don't necessarily have to introduce a class, could do it with a property
<TabAtkins> fantasai: and put that in the CQ
<flackr> q+
<fantasai> flackr: Directionally, should we consider whether "last scrolling direction" is thing we should pursue first, because it comes up in all use cases, and active scrolling direction can be pursued afterwards?
<fantasai> TabAtkins: Problems are easier and more common for recent scroll vs active scroll
<fantasai> flackr: Agree
<fantasai> flackr: Active scroll might need extra capabilities
<fantasai> Rossen8: any objections to this direction?
<TabAtkins> fantasai: We need to figure out what to do with active scroll, so we're designing a coherent syntax space fo rwhen it is tackled
<fantasai> RESOLVED: Working on scrolling queries

The CSS Working Group just discussed [css-ui][selectors][mediaqueries] Expose current scrolling direction, and agreed to the following:

RESOLVED: Add scrolling direction to scroll-state queries, with the initial syntax in the explainer but issues open for bikeshedding

The full IRC log of that discussion

<emilio> astearns: we resolved to work on this, and then you moonira added it to the agenda
<emilio> moonira: main questions that were raised last time, what kind programmatic scrolls should affect these
<emilio> ... also the other question for relative / absolute scrolls we just discussed
<emilio> ... proposal is to solve these by adding direction state to scroll-state container query
<emilio> ... syntax is similar to scroll-state
<emilio> ... you can find the explainer
<emilio> ... active scrolling would be a separate future consideration
<emilio> q+
<emilio> ... any suggestions / questions?
<astearns> ack emilio
<ydaniv> emilio: I think in general sounds good
<ydaniv> ... wondering, what happens if you have someting scrollable or not based on direction?
<noamr> q+
<ydaniv> ... wondering whether it would make sense to store the scroll direction as part of the element, and not making associated as a scrolling box
<ydaniv> ... depending on whether it's a scroll container or not
<flackr> q+
<ydaniv> ... I think you can argue both ways
<ydaniv> noamr: I think there's a similar issue in CQs
<ydaniv> ... the circular thing
<ydaniv> kizu: you can change the size of your inner element that's styled
<ydaniv> andruud: you can through scroll timelines change someting that changes it
<ydaniv> ... I was thinking it's similar, we can solve this similarly
<ydaniv> ... we have stuck, that has the same problem
<ydaniv> emilio: we have the stuck query that get stuck with the moving thing
<flackr> q-
<futhark> q+
<ydaniv> ... using the same mechanism makes sense to me
<ydaniv> andruud: I think it's in the explainer
<noamr> q-
<astearns> ack futhark
<emilio> futhark: sorry was out for a bit, but wanted to respond to the post-layout snapshotting
<astearns> https://github.com/w3c/csswg-drafts/blob/main/css-conditional-5/scroll_state_explainer.md
<ydaniv> emilio: quetion was whether this part was part of the element itself or not
<ydaniv> ... andruud convinced me that it's same as the stuck thing
<emilio> futhark: so it depends on container-type
<moonira> http://github.com/w3c/csswg-drafts/blob/main/css-conditional-5/scroll_state_explainer.md
<emilio> andruud: but where's the last scroll direction stored
<emilio> futhark: I'd assume the post layout snapshotting mechanism?
<emilio> emilio: we should really define that properly
<emilio> futhark: yeah the HTML integration is missing, working on the implementation of that atm
<noamr> q+
<astearns> ack noamr
<emilio> ... will discuss where to put it in the html
<emilio> noamr: direction is unclear, is it scrolling direction or the scrollable direction?
<emilio> ... I'd use towards / along to distinguish these?
<emilio> ... something that clarifies what the value means?
<emilio> astearns: this is about scrolling towards
<emilio> emilio: do we support scrolling-along direction?
<emilio> noamr: yeah in the spec it's part of the same query
<emilio> emilio: yeah that's confusing
<ntim> +1 to noamr
<emilio> emilio: scrollable-direction vs. scrolling-direction maybe?
<emilio> ... but extra identifier also works I guess
<ydaniv> +1 to emilio
<ntim> q+
<astearns> ack ntim
<emilio> astearns: so everybody is good with adding scrolling direction?
<emilio> ntim: I'd like smfr to be here
<emilio> ... some questions about content changes
<emilio> emilio: I think same answer that my question
<emilio> flackr: yeah that came up in the last f2f
<emilio> ntim: other question was about rubber-banding, probably shouldn't be exposed
<emilio> flackr: agreed. Rubber banding in chrome doesn't change scroll offset but probably it shouldn't change the scroll direction even if it did
<ntim> scroll-state(direction: ...) / scroll-state(allowed: ) ?
<emilio> PROPOSAL: Add scrolling direction to scroll-state queries, with the initial syntax in the explainer but issues open for bikeshedding
<emilio> ntim: would like smfr to review
<emilio> astearns: fine taking the resolution?
<emilio> emilio: impl is the same as stuck and so on
<emilio> ntim: fine to resolve then
<emilio> RESOLVED: Add scrolling direction to scroll-state queries, with the initial syntax in the explainer but issues open for bikeshedding
<emilio> astearns: re programmatic scroll are we set with the previous issue?
<emilio> moonira: yes

Navigation Menu

Repository navigation

[css-ui][selectors][mediaqueries] Expose current scrolling direction #6400

12 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

📋 Server Request & Proxy Logs

⚙️ Pengaturan Proxy Target

[css-ui][selectors][mediaqueries] Expose current scrolling direction #6400

Description

Activity

jonjohnjohnson commented on Jun 21, 2021

jeysal commented on Jul 29, 2021

bramus commented on Jun 16, 2022

chrishtr commented on Jun 16, 2022

bramus commented on Jun 17, 2022

SebastianZ commented on Jun 17, 2022

SebastianZ commented on Jun 17, 2022

12 remaining items

mirisuzanne commented on May 15, 2025

bramus commented on May 15, 2025

flackr commented on May 15, 2025

ydaniv commented on May 16, 2025

flackr commented on May 20, 2025

css-meeting-bot commented on May 21, 2025

css-meeting-bot commented on Aug 19, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions