[drawer] Create new Drawer / Sheet component

[atomiks]

Closes #38

• Nested drawer demo/logic/styling
• Background indent provider
• Handle text selection with swiping interaction
• Fix momentum when swipe dismissing
• Snap points

Preview: https://deploy-preview-3680--base-ui.netlify.app/react/components/drawer

[pkg-pr-new]

• base-ui-tanstack-start

• vite-css-base-ui-example

  pnpm add https://pkg.pr.new/mui/base-ui/@base-ui/react@3680
  

  pnpm add https://pkg.pr.new/mui/base-ui/@base-ui/utils@3680
  

commit: 7f95fa0

[mui-bot]

Bundle size report

Bundle	Parsed size	Gzip size
@base-ui/react	🔺+35.4KB(+8.44%)	🔺+11.6KB(+8.64%)

Details of bundle changes

---

Check out the code infra dashboard for more information about this PR.

[netlify]

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	7f95fa0
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/697d6fbd2a18370008dae0b0
😎 Deploy Preview	https://deploy-preview-3680--base-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[piehouserat]

any idea when this will ship? I need a drawer component fairly soon but I can always use vaul in the meantime

[atomiks]

@piehouserat probably in v1.2.0 release around mid-February

[philwolstenholme]

A neat feature would be to use a CloseWatcher to allow closing the drawer with the Android 'back' swipe gesture. This can make drawers and modals feel much more native. The browser support is Chromium only at the moment (I think?) but I usually feature detect it and fall back to an Esc key listener instead on unsupported browsers.

[oliviertassinari]

@atomiks Really cool!

I don't know if you already need feedback, maybe not, but since I'm the only one? on Android, I thought I could have a quick play on my phone, and compare with Material UI:

1. It's impossible to close the drawer, starting outside of the Popup:

VID_20260117_152111.mp4

Vaul has the same problem. But on Android, all the native apps, e.g., Google Drive supports it. It works "correctly" with Material UI. I'm used to it at this point. The value for end-users is not having to put any mental energy in think where to place your finger to start the dismissal interaction.

2. It's possible to extend the drawer to infinity, it shouldn't:

VID_20260117_151449.mp4

I guess it's an Android-only issue, that we are good on iOS, we only have this issue because we want to have resistance when going in the wrong direction, and it's a bit trickier in Android to make it work.

3. The close interaction feels too sensitive. I felt I had "cancelled" my interaction, I barely retracted the drawer, but still, it closed it:

VID_20260117_182008.mp4

We could have short interactions like this to close the drawer, but then it should take into account the velocity of the movement; this is the approach used in Material UI.

Otherwise:

• I created a start of a benchmark page https://www.notion.so/mui-org/core-Drawer-Sheet-2ebcbfe7b66080a68150cdc9e0b0ac20, to help copy the best stuff that is out there.
• In #38, linked to the relevant Shadcn issues: helps us understand a bit what those folks need (the key bugs from Vaul) and help folks find our solution.

[atomiks]

@oliviertassinari thanks for all those points, very helpful - they should be addressed in the latest update

[colmtuite]

Swipe from outside to dismiss

It's impossible to close the drawer, starting outside of the Popup
The value for end-users is not having to put any mental energy in think where to place your finger to start the dismissal interaction.

This one is controversial. There's value in not having it dismiss too, so the backdrop is a safe zone for swiping (cleaning dust off your screen or whatever). But the biggest issue is that the Drawer should feel native, and iOS does not work like this. So we should either revert this, or detect the OS and have different behaviour for each.

Swipe area to open

On YT, you can swipe a specific area of the viewport to open the Drawer, which is a nice touch. We should add this to be feature-complete.

Screen.Recording.2026-01-27.at.07.12.21.mov

[oliviertassinari]

that the Drawer should feel native, and iOS does not work like this.

Interesting, I was coming from the Android side, pushing on the "feel native" direction + upside of the approach.
+1 for a branch based on the OS then, even though I don't understand the upside of the safe zone.

[atomiks]

Swipe from outside to dismiss

@colmtuite turns out iOS isn't consistent here. Yesterday I was using Maps and it has a Drawer component that does exactly what we're doing in this PR. Honestly, it feels the best/most natural to me and allows you to sloppily swipe from above, which feels the most intuitive.

Maybe it's intentionally context-dependent for some reason?

[colmtuite]

@atomiks

turns out iOS isn't consistent here

Interesting. I can't seem to find another iOS drawer that works like this. But yeah ok, I guess the question now is do we make it configurable (and only apply the option to iOS)? Have you looked at how this works in Swift, and how to configure it?

Drawer.SwipeArea is nice. It feels too aggressive to me though. Looking at Youtube, the threshold for opening after releasing while the pointer is static, seems to be if the drawer is open to >50% of its width/height (depending on direction/position).

[atomiks]

Interesting. I can't seem to find another iOS drawer that works like this. But yeah ok, I guess the question now is do we make it configurable (and only apply the option to iOS)? Have you looked at how this works in Swift, and how to configure it?

I would not make it configurable unless requested. It doesn't seem like it's configurable and Maps uses a "custom" sheet:

Very likely it’s not using the stock sheet gesture recognizer behavior in those cases (Maps historically used custom bottom sheets well before UISheetPresentationController existed).

I would say it's not controversial though, it's probably something 99% of people don't even notice in iOS to begin with

[philwolstenholme]

This is looking fantastic, just been playing around with it on Android Chrome and it's looking and feeling great. Thank you for adding the CloseWatcher support!

[oliviertassinari]

The CloseWatcher is so good. Tweet material right there.

Having it supported in the drawer makes me feel like its missing everywhere now. The dialogs, the docs search, the docs nav

But it will take me a long time before trusting UIs that I can use the back button on a webpage and it won't go to the previous URL. A website having it would actually probably mess me up (train me to bad habits, I would want to close a dialog to the action, and instead load the previous page, and lose what I was typing in a form, nooo), it would make me want to expect all websites to have it, or have it disabled in the few that have it. Maybe because <dialog> supports it by default, people will get more used to it, and it's fine. Unclear #3905.

[oliviertassinari]

It depends on how people configure it. It's a back button or a back swipe.

Suggested change

	// CloseWatcher enables the Android back swipe gesture (Chromium-only).
	// CloseWatcher enables the Android back gesture (Chromium-only).

https://eu.community.samsung.com/t5/galaxy-s24-series/buttons-vs-swipe-gestures-what-do-you-all-use-why/td-p/12769482

[philwolstenholme]

The CloseWatcher is so good. Tweet material right there.

Having it supported in the drawer makes me feel like its missing everywhere now.

But it will take me a long time before trusting UIs that I can use the back button on a webpage and it won't go to the previous URL. A website having it would actually probably mess me up (train me to bad habits), it would make me want to expect all websites to have it, or have it disabled in the few that have it.

I think it's my favourite recent web API addition, but I know what you mean about it being a bit confusing. It's being adopted slowly and there's no way for users to tell if a site supports it. I've added it to the site I look after at work as our users are 85% mobile and I imagine the Android users are used to being able to swipe back.