Toast notifications for React. Built on Base UI Toast primitives — headless components done right. Sonner-compatible API. 8.3 KB gzipped total. No !important. No memory leaks. Your styles actually win for once.
Documentation · Why I built this · Why Base UI · Changelog
npm install @vcui/popser @base-ui/reactPeer deps: react (18 or 19), react-dom, @base-ui/react (^1.2.0). You probably have the first two already.
import { toast, Toaster } from "@vcui/popser";
import "@vcui/popser/styles";
function App() {
return (
<>
<button onClick={() => toast.success("It works")}>Toast</button>
<Toaster />
</>
);
}No Provider wrapper. No theme config. No 47-step Medium article. It just works.
Every method returns the toast ID. Use it to update, close, or track toasts.
toast("Hello world");
toast.success("Saved");
toast.error("Something broke");
toast.info("Heads up");
toast.warning("Careful");
toast.loading("Working...");Transitions through loading → success → error automatically.
toast.promise(fetchData(), {
loading: "Fetching...",
success: (data) => `Loaded ${data.count} items`,
error: (err) => `Failed: ${err.message}`,
});Return undefined from a handler to dismiss silently. Return JSX if you're feeling fancy. Full details in docs/api.md.
const id = toast.loading("Uploading...");
toast.update(id, { title: "Almost done...", description: "95%" });
toast.close(id); // close one
toast.close(); // close allSkip the default layout entirely. Render whatever you want.
toast.custom((id) => (
<div>
Your markup. Your rules.
<button onClick={() => toast.close(id)}>Dismiss</button>
</div>
));Pin a toast to a button, element, or coordinate. Think tooltips but with attitude.
toast.success("Copied!", {
anchor: buttonRef.current,
anchorSide: "top",
arrow: true,
timeout: 2000,
});Full anchor positioning docs: docs/anchored.md
toast.error("Connection lost", { deduplicate: true });
toast.error("Connection lost", { deduplicate: true }); // no-opDrop it anywhere. One instance. Configure once.
<Toaster
position="bottom-right"
limit={3}
timeout={4000}
closeButton="hover"
richColors
theme="system"
/>All props: docs/toaster.md
Import the defaults and override what you want:
import "@vcui/popser/styles"; // modular (6 files via @import)
import "@vcui/popser/styles/min"; // flat, minified, single file — 2.7 KB gzippedEverything is CSS custom properties. Override them, don't fight them:
:root {
--popser-bg: oklch(1 0 0);
--popser-fg: oklch(0.145 0 0);
--popser-border: oklch(0.922 0 0);
--popser-radius: 8px;
}Works with Tailwind, CSS modules, or raw CSS. Pass classNames to target every slot. Or go unstyled and build from scratch with data-popser-* attributes.
Full styling guide: docs/styling.md
npx shadcn add @vcode-sh/popserDetails: docs/shadcn.md
Every toast renders data-popser-id in the DOM. Select by ID in Playwright or Cypress without praying to the selector gods.
await page.locator('[data-popser-id="my-toast"]').waitFor();Full data attributes reference: docs/testing.md
| Raw | Gzipped | |
|---|---|---|
| JS (ESM) | 15.7 KB | 5.6 KB |
CSS (styles/min) |
16.6 KB | 2.7 KB |
| Total | 32.3 KB | 8.3 KB |
Sonner ships ~17 KB gzipped with CSS bundled inside the JavaScript. Popser is about half that, and the CSS is a separate opt-in file your bundler can tree-shake.
Sonner is great. I used it for years. Then I needed to style a toast without !important and the whole thing fell apart.
popser is built on Base UI Toast primitives — the headless component library built by the teams behind Radix, Floating UI, and MUI. Base UI is where React component architecture is heading in 2026, and popser is the first toast library built on top of it.
The API is Sonner-compatible so you can swap without rewriting anything. But under the hood, it's proper headless UI with ARIA live regions, F6 keyboard navigation, and styles that don't need !important to override.
- Headless primitives. Base UI renders the structure. You own the styles.
- Sonner-compatible. Same
toast.success()/toast.promise()interface. Drop-in. - No memory leaks. Singleton manager with tracked cleanup. Toasts don't ghost you.
- No hardcoded breakpoints. Mobile breakpoint is a prop. CSS-driven responsiveness.
- Accessible. ARIA live regions, priority system, keyboard navigation.
- E2E ready.
data-popser-idon every toast root. Stable selectors out of the box. - Tiny. 8.3 KB gzipped total. Five inline SVGs and a CSS spinner. Zero icon dependencies.
- Anchored toasts. Pin toasts to elements with Floating UI positioning. Arrow included.
Read the full story: Why I built this · Why Base UI, not Radix
- Toast API — all methods, options, deduplication, callbacks
- Toaster Component — props, positioning, theme, mobile
- Styling — CSS variables, classNames, Tailwind, dark mode, unstyled
- Promise Toasts — loading states, JSX results, conditional skip, finally
- Anchored Toasts — element anchoring, coordinates, arrow, positioning
- Custom Toasts — custom render functions, bypassing default layout
- shadcn Integration — registry install, next-themes, configuration
- Testing — data attributes, Playwright, Cypress, useToaster hook
- Popser vs Sonner — feature comparison, migration guide, issue tracker
- Popser vs Base UI Toast — architecture, component mapping, what we add
- Changelog — what changed, when, and why
Or just read them on the website: popser.vcui.dev/docs
Contributions welcome. Bug fixes, features, docs, tests — all of it. Check CONTRIBUTING.md for the setup and ground rules, or read popser.vcui.dev/collaborate for the longer version.
MIT - Vibe Code