{"id":45986299,"url":"https://github.com/vcode-sh/popser","last_synced_at":"2026-02-28T19:00:47.177Z","repository":{"id":341197137,"uuid":"1167060605","full_name":"vcode-sh/popser","owner":"vcode-sh","description":"Toast notifications for React. Built on Base UI — the headless primitives era starts now. Sonner-compatible API. 7.4 KB gzipped. No !important. No memory leaks.","archived":false,"fork":false,"pushed_at":"2026-02-28T12:56:14.000Z","size":764,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-28T16:37:06.722Z","etag":null,"topics":["base-ui","component","notifications","react","shadcn","sonner","toast","ui"],"latest_commit_sha":null,"homepage":"https://popser.vcui.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vcode-sh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-25T22:43:07.000Z","updated_at":"2026-02-28T12:56:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vcode-sh/popser","commit_stats":null,"previous_names":["vcode-sh/popser"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/vcode-sh/popser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vcode-sh%2Fpopser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vcode-sh%2Fpopser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vcode-sh%2Fpopser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vcode-sh%2Fpopser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vcode-sh","download_url":"https://codeload.github.com/vcode-sh/popser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vcode-sh%2Fpopser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29948228,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T18:42:55.706Z","status":"ssl_error","status_checked_at":"2026-02-28T18:42:48.811Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["base-ui","component","notifications","react","shadcn","sonner","toast","ui"],"created_at":"2026-02-28T19:00:46.417Z","updated_at":"2026-02-28T19:00:47.161Z","avatar_url":"https://github.com/vcode-sh.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# popser\n\n[![npm version](https://img.shields.io/npm/v/@vcui/popser)](https://www.npmjs.com/package/@vcui/popser)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-3178c6)](https://www.typescriptlang.org/)\n\nToast notifications for React. Built on [Base UI](https://base-ui.com) 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.\n\n**[Documentation](https://popser.vcui.dev/docs)** · **[Why I built this](https://popser.vcui.dev/why)** · **[Why Base UI](https://popser.vcui.dev/why-base-ui)** · **[Changelog](https://popser.vcui.dev/docs/changelog)**\n\n## Install\n\n```bash\nnpm install @vcui/popser @base-ui/react\n```\n\nPeer deps: `react` (18 or 19), `react-dom`, `@base-ui/react` (^1.2.0). You probably have the first two already.\n\n## Quick Start\n\n```tsx\nimport { toast, Toaster } from \"@vcui/popser\";\nimport \"@vcui/popser/styles\";\n\nfunction App() {\n  return (\n    \u003c\u003e\n      \u003cbutton onClick={() =\u003e toast.success(\"It works\")}\u003eToast\u003c/button\u003e\n      \u003cToaster /\u003e\n    \u003c/\u003e\n  );\n}\n```\n\nNo Provider wrapper. No theme config. No 47-step Medium article. It just works.\n\n## Toast API\n\nEvery method returns the toast ID. Use it to update, close, or track toasts.\n\n```ts\ntoast(\"Hello world\");\ntoast.success(\"Saved\");\ntoast.error(\"Something broke\");\ntoast.info(\"Heads up\");\ntoast.warning(\"Careful\");\ntoast.loading(\"Working...\");\n```\n\n### Promise toasts\n\nTransitions through loading → success → error automatically.\n\n```ts\ntoast.promise(fetchData(), {\n  loading: \"Fetching...\",\n  success: (data) =\u003e `Loaded ${data.count} items`,\n  error: (err) =\u003e `Failed: ${err.message}`,\n});\n```\n\nReturn `undefined` from a handler to dismiss silently. Return JSX if you're feeling fancy. Full details in **[docs/api.md](docs/api.md)**.\n\n### Update and close\n\n```ts\nconst id = toast.loading(\"Uploading...\");\ntoast.update(id, { title: \"Almost done...\", description: \"95%\" });\ntoast.close(id);   // close one\ntoast.close();     // close all\n```\n\n### Custom toasts\n\nSkip the default layout entirely. Render whatever you want.\n\n```ts\ntoast.custom((id) =\u003e (\n  \u003cdiv\u003e\n    Your markup. Your rules.\n    \u003cbutton onClick={() =\u003e toast.close(id)}\u003eDismiss\u003c/button\u003e\n  \u003c/div\u003e\n));\n```\n\n### Anchored toasts\n\nPin a toast to a button, element, or coordinate. Think tooltips but with attitude.\n\n```ts\ntoast.success(\"Copied!\", {\n  anchor: buttonRef.current,\n  anchorSide: \"top\",\n  arrow: true,\n  timeout: 2000,\n});\n```\n\nFull anchor positioning docs: **[docs/anchored.md](docs/anchored.md)**\n\n### Deduplication\n\n```ts\ntoast.error(\"Connection lost\", { deduplicate: true });\ntoast.error(\"Connection lost\", { deduplicate: true }); // no-op\n```\n\n## Toaster\n\nDrop it anywhere. One instance. Configure once.\n\n```tsx\n\u003cToaster\n  position=\"bottom-right\"\n  limit={3}\n  timeout={4000}\n  closeButton=\"hover\"\n  richColors\n  theme=\"system\"\n/\u003e\n```\n\nAll props: **[docs/toaster.md](docs/toaster.md)**\n\n## Styling\n\nImport the defaults and override what you want:\n\n```ts\nimport \"@vcui/popser/styles\";       // modular (6 files via @import)\nimport \"@vcui/popser/styles/min\";   // flat, minified, single file — 2.7 KB gzipped\n```\n\nEverything is CSS custom properties. Override them, don't fight them:\n\n```css\n:root {\n  --popser-bg: oklch(1 0 0);\n  --popser-fg: oklch(0.145 0 0);\n  --popser-border: oklch(0.922 0 0);\n  --popser-radius: 8px;\n}\n```\n\nWorks with Tailwind, CSS modules, or raw CSS. Pass `classNames` to target every slot. Or go `unstyled` and build from scratch with `data-popser-*` attributes.\n\nFull styling guide: **[docs/styling.md](docs/styling.md)**\n\n## shadcn\n\n```bash\nnpx shadcn add @vcode-sh/popser\n```\n\nDetails: **[docs/shadcn.md](docs/shadcn.md)**\n\n## E2E Testing\n\nEvery toast renders `data-popser-id` in the DOM. Select by ID in Playwright or Cypress without praying to the selector gods.\n\n```ts\nawait page.locator('[data-popser-id=\"my-toast\"]').waitFor();\n```\n\nFull data attributes reference: **[docs/testing.md](docs/testing.md)**\n\n## Bundle Size\n\n| | Raw | Gzipped |\n|---|---|---|\n| JS (ESM) | 15.7 KB | 5.6 KB |\n| CSS (`styles/min`) | 16.6 KB | 2.7 KB |\n| **Total** | **32.3 KB** | **8.3 KB** |\n\nSonner 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.\n\n## Why popser?\n\nSonner is great. I used it for years. Then I needed to style a toast without `!important` and the whole thing fell apart.\n\npopser is built on [Base UI](https://base-ui.com) 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.\n\nThe 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.\n\n- **Headless primitives.** Base UI renders the structure. You own the styles.\n- **Sonner-compatible.** Same `toast.success()` / `toast.promise()` interface. Drop-in.\n- **No memory leaks.** Singleton manager with tracked cleanup. Toasts don't ghost you.\n- **No hardcoded breakpoints.** Mobile breakpoint is a prop. CSS-driven responsiveness.\n- **Accessible.** ARIA live regions, priority system, keyboard navigation.\n- **E2E ready.** `data-popser-id` on every toast root. Stable selectors out of the box.\n- **Tiny.** 8.3 KB gzipped total. Five inline SVGs and a CSS spinner. Zero icon dependencies.\n- **Anchored toasts.** Pin toasts to elements with Floating UI positioning. Arrow included.\n\nRead the full story: **[Why I built this](https://popser.vcui.dev/why)** · **[Why Base UI, not Radix](https://popser.vcui.dev/why-base-ui)**\n\n## Documentation\n\n- **[Toast API](docs/api.md)** — all methods, options, deduplication, callbacks\n- **[Toaster Component](docs/toaster.md)** — props, positioning, theme, mobile\n- **[Styling](docs/styling.md)** — CSS variables, classNames, Tailwind, dark mode, unstyled\n- **[Promise Toasts](docs/promise.md)** — loading states, JSX results, conditional skip, finally\n- **[Anchored Toasts](docs/anchored.md)** — element anchoring, coordinates, arrow, positioning\n- **[Custom Toasts](docs/custom.md)** — custom render functions, bypassing default layout\n- **[shadcn Integration](docs/shadcn.md)** — registry install, next-themes, configuration\n- **[Testing](docs/testing.md)** — data attributes, Playwright, Cypress, useToaster hook\n- **[Popser vs Sonner](docs/popser-sonner.md)** — feature comparison, migration guide, issue tracker\n- **[Popser vs Base UI Toast](docs/popser-toast.md)** — architecture, component mapping, what we add\n- **[Changelog](CHANGELOG.md)** — what changed, when, and why\n\nOr just read them on the website: **[popser.vcui.dev/docs](https://popser.vcui.dev/docs)**\n\n## Contributing\n\nContributions welcome. Bug fixes, features, docs, tests — all of it. Check **[CONTRIBUTING.md](CONTRIBUTING.md)** for the setup and ground rules, or read **[popser.vcui.dev/collaborate](https://popser.vcui.dev/collaborate)** for the longer version.\n\n## License\n\nMIT - [Vibe Code](https://vcode.sh)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvcode-sh%2Fpopser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvcode-sh%2Fpopser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvcode-sh%2Fpopser/lists"}