[toast] Add useToastActions hook to avoid unnecessary re-renders

[Yevgeni-Esh]

Fixes #4234

Problem

useToastManager() unconditionally calls store.useState('toasts'), which registers a useSyncExternalStore subscription. This means every component that calls useToastManager() re-renders on every toast lifecycle event (add, close, update, timeout) — even if the component only destructures action methods like { add } and never reads the toasts array.

// This button re-renders on every toast state change, despite only using `add`
function SaveButton() {
  const { add } = Toast.useToastManager();
  return <button onClick={() => add({ title: 'Saved!' })}>Save</button>;
}

The action methods (addToast, closeToast, etc.) are stable references — arrow functions on the ToastStore class instance. But the subscription is registered before the caller destructures the return value, so destructuring only { add } doesn't help.

Solution

Add a new useToastActions() hook that returns only the stable action methods (add, close, update, promise) without subscribing to state:

• No store.useState() call → no useSyncExternalStore subscription → zero re-renders from toast state changes
• ToastContext holds the ToastStore instance (stable ref created via useRefWithInit), so useContext won't trigger re-renders either
• The action methods are arrow functions on the class instance — their references are stable

Usage

// Components that only FIRE toasts — zero re-renders from toast state
function SaveButton() {
  const { add } = Toast.useToastActions();
  return <button onClick={() => add({ title: 'Saved!' })}>Save</button>;
}

// Components that DISPLAY toasts — subscribe to state (unchanged)
function ToastList() {
  const { toasts } = Toast.useToastManager();
  return toasts.map((toast) => <Toast.Root key={toast.id} toast={toast} />);
}

Changes

• New hook: packages/react/src/toast/useToastActions.ts
• Exports: Added to index.parts.ts and index.ts
• Tests: 5 new tests including a render count assertion that verifies the component does not re-render when toasts are added/dismissed
• Type spec: Mirrors useToastManager.spec.tsx — validates generic <Data> inference
• Docs: Added useToastActions section to toast docs with return value reference and usage guidance
• Public types: Updated test/public-types/toast.tsx with UseToastActionsReturnValue
• Error codes: New code 93 for missing provider error

All existing useToastManager tests (31/31) continue to pass.

• I have followed (at least) the PR section of the contributing guide.

[pkg-pr-new]

• base-ui-tanstack-start

• vite-css-base-ui-example

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

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

commit: 0af6640

[mui-bot]

Bundle size report

Bundle	Parsed size	Gzip size
@base-ui/react	🔺+196B(+0.04%)	🔺+29B(+0.02%)

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	4e45a5f
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/69a55733b9ac160008e3fd34
😎 Deploy Preview	https://deploy-preview-4233--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.

[atomiks]

This looks okay, but you can also use the global manager to avoid re-renders, and might be better than adding a new API to the mix here

[Yevgeni-Esh]

I think using just global manager is not ideal

in a nested page or component causing re-renders... i don't think its best practice to use the ref of the global manager object

re-render example
https://stackblitz.com/edit/9xjrqjfk-mu5uzrrf?file=src%2FApp.tsx
using const { add } = Toast.useToastManager();
like it says to use in the documentation.

no rerender
https://stackblitz.com/edit/9xjrqjfk?file=src%2FApp.tsx
using toastManager.add({

but this means you must make an export of export const toastManager = Toast.createToastManager(); in the main app and import it from a page/component and not use it from the provider

but i get that this involves new API...

or... maybe just update the docs that doing const { add } = Toast.useToastManager(); may cause re-renders so they should do import toastManager and do toastManager.add? :)

[Yevgeni-Esh]

@atomiks
WDYT?