Skip to content

fix(toast): keep error and action toasts until the user closes them - #687

Open
wemra3 wants to merge 20 commits into
mainfrom
fix/toast-defaults
Open

wemra3 wants to merge 20 commits into
mainfrom
fix/toast-defaults

Conversation

@wemra3

@wemra3 wemra3 commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The toast docs and the implementation did not match. <Toaster /> passes no position, count or duration, so Sonner 2.0.8 defaults apply (bottom right, up to 3 visible, 4 s for every type). The docs said top right, one at a time, success 3 s, and "error is sticky". These docs are also emitted into the consumer skill, so an AI agent could report a failed save only through toast.error and the message would close after 4 s.

This PR fixes the two sides separately, as agreed in tailor-inc/platform-planning#2349:

  • Docs follow the implementation for position and count. patterns/interaction-toast and api/use-toast now describe bottom right, up to 3 visible, 4 s, and add one rule: do not make a toast the only way to do something (an Undo in a toast needs a way back on the page too).

  • The implementation follows the docs for errors. useToast wraps Sonner's toast and gives toast.error, the error state of toast.promise, and any toast with an action the defaults duration: Infinity and closeButton: true. A duration or closeButton passed by the caller wins. toast.custom passes through, because Sonner draws neither the action nor the close button for it. The return type stays typeof toast. A call without an action that updates one of these toasts by id (for example toast.success("Saved", { id }) after toast.error) resets duration and closeButton to Sonner's defaults unless it passes its own, because Sonner merges an update by id into the stored toast. A toast.promise call with an action also gets the action defaults, because Sonner shows that action in the loading and success states.

  • The app can change these defaults field by field. AppShell takes toastDefaults?: { error?, action? }, next to locale and timeZone. Each kind takes { duration?, closeButton? } with at least one field set. The built-in default is written out in AppShell ({ duration: Infinity, closeButton: true }), so it does not depend on Sonner's defaults. A field set in toastDefaults replaces that field only; fields and kinds left out keep the built-in default. An empty object such as error: {} is a type error. To keep the old behavior, an app sets both fields: { duration: 4000, closeButton: false }. AppShell compares toastDefaults by value, so an inline object does not rebuild the config context or change the toast that useToast returns on every render. The changeset is minor, and docs/migrations.md has a 1.21.0 entry with the steps to keep the old behavior.

  • dismissible: false is left alone. A toast the user is not allowed to close does not get the sticky defaults; it keeps Sonner's behavior (no close button, closes after 4 s), as before this PR. For toast.promise, only the error state's own dismissible counts.

Not changed: position, visible count, success/info/warning toasts without an action, and the z-index from #668.

Part of tailor-inc/platform-planning#2349

Why useToast and not <Toaster toastOptions>

toastOptions.duration applies to every type, so it cannot keep errors open while success toasts still close. Sonner resolves toast.duration || toasterDuration || 4000 and toast.closeButton ?? toasterCloseButton per toast, so the per-call defaults are the only place where this can be done without changing the visible count or position.

Test plan

  • use-toast.test.tsx: error and action toasts get duration: Infinity and closeButton: true; caller's duration / closeButton (including an explicit undefined) win; success, info and plain toasts are unchanged; with fake timers only the error toast survives 5 s; toast.promise error state gets the defaults, the call's and the result's own options win, and the success state is unchanged; a toast.promise with an action keeps its success toast, and its error state still uses the error default.
  • toastDefaults: a field overrides only that field; { duration: 4000, closeButton: false } restores the old behavior; error: {} and action: {} are type errors (@ts-expect-error); a real AppShell re-rendered with an inline toastDefaults keeps the same toast until a value changes.
  • pnpm type-check, pnpm lint, pnpm test (core: 3112 tests), turbo run check-dts, pnpm docs:sync, pnpm docs:check.
  • vite example, DataTable Lab inline editing: a rejected price shows the error toast; it is still there after 6.5 s with a close button, and the close button removes it.
  • vite example, a test page with an inline toastDefaults. No setting: error, action and toast.promise with an action stay with a close button; success and toast.promise without an action close after 4 s. { duration: 4000, closeButton: false } for both kinds: every toast closes after 4 s without a close button. error: { duration: 10_000 }: errors close after 10 s and keep the close button; action toasts stay.

Notes for review

  • A toast imported from sonner directly does not get the new defaults. The docs say so.
  • The close button's aria-label is Sonner's default "Close toast" (English only). Wiring it to defineI18nLabels is a separate change.
  • The inline editing demo in the vite example calls toast.error on every rejected commit; with sticky errors these now stack up to 3. The demo is out of scope here; a follow-up can give the call an id so it replaces the previous one.

🤖 Generated with Claude Code

`useToast` now wraps sonner's `toast` and gives `toast.error`, the error
state of `toast.promise`, and any toast with an `action` the defaults
`duration: Infinity` and `closeButton: true`. Options passed by the caller
win. `toast.custom` passes through, because sonner draws neither the action
nor the close button for it.

The toast docs described a position, count and durations that the
`<Toaster />` never set (top right, one at a time, success 3 s, error
sticky). They now describe sonner's real defaults (bottom right, up to 3,
4 s) plus the two defaults this change adds, and tell consumers not to make
a toast the only way to do something.

Part of tailor-inc/platform-planning#2349

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@wemra3
wemra3 requested a review from a team as a code owner November 8, 2026 05:57
@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Code Metrics Report

main (923933d) #687 (f13e605) +/-
Coverage 62.9% 63.0% +0.0%
Test Execution Time 4m3s 2m58s -1m5s
Details
  |                     | main (923933d) | #687 (f13e605) |  +/-  |
  |---------------------|----------------|----------------|-------|
+ | Coverage            |          62.9% |          63.0% | +0.0% |
  |   Files             |            294 |            294 |     0 |
  |   Lines             |          13483 |          13592 |  +109 |
+ |   Covered           |           8485 |           8564 |   +79 |
+ | Test Execution Time |           4m3s |          2m58s | -1m5s |

Code coverage of files in pull request scope (14.8% → 15.7%, patch 94.0%)

Files Coverage +/- Patch Coverage Status
dist/auth-context-DKJ0CX7P.js 0.0% -46.2% - affected
packages/core/dist/app-shell.js 8.7% +0.1% - affected
packages/core/dist/auth-context-3riIykdl.js 46.3% +46.3% - affected
packages/core/src/components/appshell/appshell.tsx 91.1% +2.2% 100.0% modified
packages/core/src/components/data-table/pagination.tsx 95.4% +0.4% - affected
packages/core/src/contexts/appshell-context.tsx 94.4% 0.0% - modified
packages/core/src/hooks/use-toast.ts 92.6% +42.6% 92.6% modified
packages/core/src/index.ts 0.0% 0.0% - modified

Reported by octocov

Hiroki Uemura and others added 2 commits November 8, 2026 16:37
Sonner merges an update by `id` into the stored toast, so the `duration: Infinity`
and `closeButton: true` that `useToast` gives an error or action toast survived
into a later `toast.success("Saved", { id })`, which then never closed. A call
without an `action` that updates by `id` now passes an explicit `undefined` for
both unless the caller sets them.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Comment thread .changeset/sticky-error-toasts.md Resolved

@interacsean interacsean left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there’s an edge here with dismissible: false. Sonner still renders the close button when a toast isn’t dismissible, but the click does nothing (onClick: disabled || !dismissible ? () => {} : …).

I checked this in a quick test: the button renders, and after clicking it the toast is still there. So toast.error("…", { dismissible: false }) used to go away after 4s. Now it stays forever with a × that doesn’t work. The docs cover the “stays until toast.dismiss(id)” part, but a dead button is a bit odd for the user.

What do you think about defaulting the close button off when the caller opts out of dismissing?

closeButton: data?.closeButton ?? data?.dismissible !== false,

wemra3 and others added 6 commits November 9, 2026 15:54
With `dismissible: false`, Sonner draws a close button that does nothing and
ignores swipe and Escape, so a sticky default would leave `toast.dismiss(id)`
as the only way to end the toast. Such toasts now keep Sonner's defaults (no
close button, 4 s), as before. For `toast.promise`, only the error state's own
`dismissible` counts, because Sonner resets the flag when the loading toast
becomes the error toast.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
`useToast` now reads its per-kind defaults from the AppShell configuration. The
built-in defaults are unchanged (`error` and `action` toasts stay until the user
closes them, with a close button). An app replaces a kind as a whole with
`<AppShell toastDefaults={{ error: {} }}>`, which falls back to sonner's own
defaults for that kind, or sets its own `duration` / `closeButton`.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
unicorn/consistent-function-scoping: it captures nothing from createToast.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@wemra3

wemra3 commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor Author

@interacsean Replying to your review about dismissible: false.

Thank you, I reproduced this. I went one step further than hiding the close button: when the caller passes dismissible: false, useToast does not apply the sticky defaults at all. The toast keeps Sonner's own behavior (no close button, closes after 4 seconds), the same as before this PR. A caller who wants it to stay until the app closes it passes duration: Infinity, as before.

The reason: the sticky defaults exist so that the user can read an error and close it. A toast the user is not allowed to close should not be kept open by them. Hiding the close button alone would still leave it open forever.

For toast.promise, only the error state's own dismissible counts, because Sonner resets the flag when the loading toast becomes the error toast. Fixed in 729f520, with tests and a docs update.

wemra3 and others added 9 commits November 13, 2026 09:36
…inds

Following the review on #687:

- The built-in default `{ duration: Infinity, closeButton: true }` is
  written out in AppShell instead of relying on Sonner's defaults.
- A field set in `toastDefaults` replaces that field only; fields and
  kinds left out keep the built-in default.
- An empty object for a kind (`error: {}`, `action: {}`) is a type error,
  through a generic `AtLeastOne<T>` utility.
- docs/migrations.md gets a 1.21.0 entry with the steps to keep the
  previous behavior.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The previous commit was formatted with a print width that is not the
repository's, which rewrapped unrelated lines in use-toast.test.tsx and
appshell-context.tsx. This restores them. No behavior change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nto fix/toast-defaults

# Conflicts:
#	docs-manifest.json
`toastDefaults={{ ... }}` written inline is a new object on every render.
The configurations memo depended on its identity, so every AppShell render
rebuilt the config context and `useToast` returned a new `toast`. An effect
with `toast` in its dependencies then ran again and could stack duplicate
sticky error toasts.

AppShell now keys `toastDefaults` by its values. A test renders the real
AppShell, re-renders it with an inline object, and checks that `toast` keeps
its identity until a value changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sonner copies a call-level `action` into the loading toast and merges the
success state into it, so the success toast shows the action but closed
after 4 s. `useToast` now gives such a call the action defaults. The error
state is resolved first from the call as written, so it keeps the error
default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@wemra3

wemra3 commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the follow-up, and for the clear suggestion. I updated the PR.

  • The defaults are now set in AppShell: { duration: Infinity, closeButton: true }. They no longer depend on Sonner's defaults.
  • A field in toastDefaults overrides only that field. Other fields and kinds keep the default.
  • An empty object such as error: {} is now a type error (AtLeastOne<T>).
  • docs/migrations.md has a 1.21.0 entry that shows how to keep the previous behavior.

While testing, I also fixed two related issues:

  • toastDefaults written inline no longer rebuilds the config context on every render. AppShell now compares it by value, so useToast() keeps returning the same toast.
  • toast.promise with an action now keeps its success toast until the user closes it, like other toasts with an action.

Could you take another look when you have time?

Hiroki Uemura and others added 2 commits November 18, 2026 20:27
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

# Conflicts:
#	docs-manifest.json
@IzumiSy

IzumiSy commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Looks good now! ✅

Leave the final approval to @interacsean

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants