Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
ddc120a
fix(toast): keep error and action toasts until the user closes them
Nov 8, 2026
228389d
fix(toast): reset sticky defaults when a toast is updated by id
Nov 8, 2026
73258ee
Merge branch 'main' into fix/toast-defaults
wemra3 Nov 8, 2026
8df6d72
Merge branch 'main' into fix/toast-defaults
wemra3 Nov 9, 2026
e8b3ba7
Merge branch 'main' into fix/toast-defaults
wemra3 Nov 9, 2026
729f520
fix(toast): leave non-dismissible toasts on Sonner's defaults
Nov 9, 2026
8c486c4
feat(toast): add toastDefaults to AppShell
Nov 11, 2026
d29f5a4
Merge remote-tracking branch 'origin/main' into wip/toast-dismissible
Nov 11, 2026
1f2a06e
refactor(toast): hoist applyDefault to module scope
Nov 11, 2026
f316a24
Merge branch 'main' into fix/toast-defaults
wemra3 Nov 13, 2026
a4b8382
Merge branch 'main' into fix/toast-defaults
wemra3 Nov 16, 2026
ae7c2fb
Merge remote-tracking branch 'origin/main' into fix/toast-defaults
Nov 17, 2026
2cbc099
feat(toast): override toastDefaults field by field and reject empty k…
Nov 17, 2026
88db3af
Merge branch 'fix/toast-defaults' of https://github.com/tailor-platfo…
Nov 17, 2026
62eb652
style(toast): drop formatting-only changes from the previous commit
Nov 18, 2026
2c48058
Merge branch 'main' of https://github.com/tailor-platform/app-shell i…
Nov 18, 2026
894bc9b
fix(toast): keep toastDefaults stable when it is written inline
Nov 18, 2026
f4df188
fix(toast): keep the success state of toast.promise with an action
Nov 18, 2026
a50d480
Merge commit '923933d' into fix/toast-defaults
Nov 18, 2026
ae4a42f
Merge branch 'main' into fix/toast-defaults
wemra3 Nov 18, 2026
56c3cb3
docs(toast): give repeatable errors a stable id
interacsean Nov 18, 2026
b57764c
Merge branch 'main' into fix/toast-defaults
wemra3 Nov 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions .changeset/sticky-error-toasts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
"@tailor-platform/app-shell": minor
---

Error toasts, and toasts with an `action`, now stay until the user closes them. `useToast` gives `toast.error(...)`, the error state of `toast.promise(...)`, and any call with an `action` the defaults `duration: Infinity` and `closeButton: true`. Before, Sonner closed every toast after 4 seconds, so a failed save could disappear before the user read it, and an Undo could vanish while the user reached for it.
Comment thread
IzumiSy marked this conversation as resolved.
Resolved

This changes what users see after the update. To keep the previous behavior, or to set your own defaults, use the new `toastDefaults` prop of `AppShell`. A field set there replaces that field only; fields and kinds left out keep the new default. An empty object such as `error: {}` is a type error. See the migration guide (`docs/migrations.md`, 1.21.0).

```tsx
// The previous behavior (4 seconds, no close button) for both kinds
<AppShell
toastDefaults={{
error: { duration: 4000, closeButton: false },
action: { duration: 4000, closeButton: false },
}}
modules={modules}
/>
```

A `duration` or `closeButton` passed to the call still wins:

```ts
toast.error("Retrying in 5s", { duration: 5000 }); // closes after 5 seconds
```

A call without an `action` that updates one of these toasts by `id` resets `duration` and `closeButton` to Sonner's defaults unless it passes its own. `toast.custom`, toasts with `dismissible: false`, and success, info, warning and plain toasts without an `action` keep Sonner's defaults. The position (bottom right), the number of visible toasts (3) and the z-index are unchanged. A `toast` imported from `sonner` directly does not get the new defaults.

The toast docs (`patterns/interaction-toast`, `api/use-toast`) now describe the real position, count and durations. They used to say top right, one at a time, and 3 seconds for success.
26 changes: 13 additions & 13 deletions docs-manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -115,10 +115,10 @@
"claims": [],
"symbols": ["AppShell", "AppShellProps"],
"hashes": {
"typeSurface": "51313066e142afc2",
"outline": "25fb9b8ab6949331",
"typeSurface": "5214717584b72041",
"outline": "9b3b04b96cf99581",
"snapshot": null,
"outputMd": "cd57abd4909118a4",
"outputMd": "4f56932d1dab938a",
"examples": null
}
},
Expand Down Expand Up @@ -1028,9 +1028,9 @@
"symbols": [],
"hashes": {
"typeSurface": null,
"outline": "45b23abe90e466b2",
"outline": "4ede6f17c870d838",
"snapshot": null,
"outputMd": "f68bdab855730f48",
"outputMd": "fbdc96bd3d3d0140",
"examples": "7089e7331b95df31"
}
},
Expand Down Expand Up @@ -1130,9 +1130,9 @@
"symbols": [],
"hashes": {
"typeSurface": null,
"outline": "e88bb360eb853c34",
"outline": "aa7644812db897fd",
"snapshot": null,
"outputMd": "19ca77c7802ca5f6",
"outputMd": "597b3a3b3f96a89c",
"examples": null
}
},
Expand Down Expand Up @@ -1790,9 +1790,9 @@
"symbols": [],
"hashes": {
"typeSurface": null,
"outline": "9100b0606aa15761",
"outline": "0fc65140da8f7dff",
"snapshot": null,
"outputMd": "3f763c8074704709",
"outputMd": "90d80eef666e4cb4",
"examples": "0dce35625d5e56cf"
}
},
Expand Down Expand Up @@ -1828,7 +1828,7 @@
"packages/core/skills/app-shell-patterns/references/components/activity-card.md": "230039d9f96fd264",
"packages/core/skills/app-shell-patterns/references/components/ai-chat.md": "008761ccc93ef0fe",
"packages/core/skills/app-shell-patterns/references/components/alert.md": "9b237d9c19b54102",
"packages/core/skills/app-shell-patterns/references/components/app-shell.md": "cd57abd4909118a4",
"packages/core/skills/app-shell-patterns/references/components/app-shell.md": "4f56932d1dab938a",
"packages/core/skills/app-shell-patterns/references/components/appearance-switcher.md": "b55f1d538651d467",
"packages/core/skills/app-shell-patterns/references/components/attachment.md": "8922f126009ee1df",
"packages/core/skills/app-shell-patterns/references/components/autocomplete.md": "f3179004d35f8c88",
Expand Down Expand Up @@ -1897,7 +1897,7 @@
"packages/core/skills/app-shell-patterns/references/api/use-route-error.md": "1a44180ec84ce4b9",
"packages/core/skills/app-shell-patterns/references/api/use-theme.md": "000e2603cef83d47",
"packages/core/skills/app-shell-patterns/references/api/use-time-zone.md": "717d6989930fb8c8",
"packages/core/skills/app-shell-patterns/references/api/use-toast.md": "3f763c8074704709",
"packages/core/skills/app-shell-patterns/references/api/use-toast.md": "90d80eef666e4cb4",
"packages/core/skills/app-shell-patterns/references/patterns/form-composer.md": "ed187ac3a0773d3d",
"packages/core/skills/app-shell-patterns/references/patterns/form-modal.md": "a0d3c952b0b10351",
"packages/core/skills/app-shell-patterns/references/patterns/form-sectioned.md": "d31cd3ae6ad0790c",
Expand All @@ -1906,11 +1906,11 @@
"packages/core/skills/app-shell-patterns/references/patterns/i18n-labels.md": "d9f0851d9c98ecfe",
"packages/core/skills/app-shell-patterns/references/patterns/interaction-confirm.md": "2db70f423c6fdf97",
"packages/core/skills/app-shell-patterns/references/patterns/interaction-multi-select.md": "253fcea1c4e5a42c",
"packages/core/skills/app-shell-patterns/references/patterns/interaction-toast.md": "f68bdab855730f48",
"packages/core/skills/app-shell-patterns/references/patterns/interaction-toast.md": "fbdc96bd3d3d0140",
"packages/core/skills/app-shell-patterns/references/pages/document-collection.md": "e79d9120d86db198",
"packages/core/skills/app-shell-patterns/references/pages/document-detail.md": "e07c7fee2478a21d",
"packages/core/skills/app-shell-patterns/SKILL.md": "18efee79280174e7",
"packages/core/skills/app-shell-upgrade/references/migrations.md": "9bd2735c34fd35e3",
"packages/core/skills/app-shell-upgrade/references/migrations.md": "565afc6a837ba8da",
"packages/core/skills/app-shell-upgrade/SKILL.md": "f9be942f3e596c00"
}
}
16 changes: 16 additions & 0 deletions docs-src/components/app-shell.docs.outline.md
Original file line number Diff line number Diff line change
Expand Up @@ -228,6 +228,22 @@ Supported locales: `en`, `ja`

Access the configured timezone in components using [`useTimeZone`](../api/use-time-zone.md).

### toastDefaults

- **Type:** `{ error?: ToastDefault; action?: ToastDefault }` where `ToastDefault` is `{ duration?: number; closeButton?: boolean }` with at least one field set (optional)
- **Default:** `error` and `action` both `{ duration: Infinity, closeButton: true }`
- **Description:** Options [`useToast`](../api/use-toast.md) applies to a toast when the call does not set them. `error` covers `toast.error(...)` and the error state of `toast.promise(...)`; `action` covers any toast with an `action`. With the defaults, these toasts stay until the user closes them and show a close button. A field set here replaces that field only; fields and kinds left out keep the default. An empty object such as `error: {}` is a type error; leave the kind out instead.

```tsx
// Errors close after 4 seconds without a close button, as before 1.21.0;
// toasts with an action still stay.
<AppShell toastDefaults={{ error: { duration: 4000, closeButton: false } }} modules={modules}>
{/* ... */}
</AppShell>
```

Toasts with `dismissible: false` always keep sonner's defaults, and a `duration` or `closeButton` passed to the call always wins. See [useToast → Defaults](../api/use-toast.md#defaults).

### errorBoundary

- **Type:** `ErrorBoundaryComponent` (optional)
Expand Down
29 changes: 29 additions & 0 deletions docs-src/guides/migrations.docs.outline.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ Each entry states which versions are affected, what breaks, how to detect it, an

| Version | Change |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 1.21.0 | [Error and action toasts stay until the user closes them](#1210-error-and-action-toasts-stay-until-the-user-closes-them) |
| 1.21.0 | [Testing helpers deprecated in favour of TestingProvider](#1210-testing-helpers-deprecated-in-favour-of-testingprovider) |
| 1.20.0 | [z-index tokens renamed; old names are aliases](#1200-z-index-tokens-renamed-old-names-are-aliases) |
| 1.18.0 | [Destructive colours now resolve to the danger roles](#1180-destructive-colours-now-resolve-to-the-danger-roles) |
Expand All @@ -30,6 +31,34 @@ Each entry states which versions are affected, what breaks, how to detect it, an
| 1.0.2 | [`Toaster` no longer accepts `richColors`](#102-toaster-no-longer-accepts-richcolors) |
| before 1.0 | [Pre-1.0 breaking changes](#before-10) |

## 1.21.0: error and action toasts stay until the user closes them

**Applies to:** apps that show toasts through `useToast`.

Before 1.21.0, every toast closed after 4 seconds and had no close button, because AppShell passed no options and Sonner's defaults applied. From 1.21.0, `toast.error(...)`, the error state of `toast.promise(...)`, and any toast with an `action` get `duration: Infinity` and `closeButton: true`: they stay until the user closes them. Success, info, warning and plain toasts without an `action` are unchanged. Nothing errors; the change is only visible on screen.

How to detect it: search the app for `toast.error(`, `toast.promise(` and toasts with `action:`. Look for places that show many errors in a row (for example, one per rejected edit): up to 3 toasts are visible, and with sticky errors they now stay until closed. Also check code that relied on an error toast closing by itself.

What to change:

- To keep the previous behavior, set both fields for the kind in the `toastDefaults` prop of `AppShell`. A field set there replaces that field only, so both fields are needed:

```tsx
<AppShell
toastDefaults={{
error: { duration: 4000, closeButton: false },
action: { duration: 4000, closeButton: false },
}}
modules={modules}
/>
```

- To change one field, set only that field. `toastDefaults={{ error: { duration: 10_000 } }}` closes errors after 10 seconds and keeps the close button.
- To change a single call, pass `duration` or `closeButton` to it. The call's options win over `toastDefaults`.
- If a screen shows many errors in a row, give the call an `id` so that the new toast replaces the previous one: `toast.error(message, { id: "price-error" })`.

An empty object for a kind, such as `error: {}`, is a type error. The prop is documented in [AppShell](./components/app-shell.md#toastdefaults), and the toast rules in [`useToast`](./api/use-toast.md).

## 1.21.0: testing helpers deprecated in favour of TestingProvider

**Applies to:** tests importing `AppShell` or `TestAppShellProps` from `@tailor-platform/app-shell/testing`.
Expand Down
60 changes: 59 additions & 1 deletion docs-src/hooks/use-toast.docs.outline.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: Hook for displaying toast notifications

# useToast

React hook to display toast notifications for user feedback. It returns the `toast` function exported by [sonner](https://sonner.emilkowal.ski/toast). The built-in layouts (`SidebarLayout`, `GlobalHeaderLayout`) already render the toaster, so no provider setup is needed.
React hook to display toast notifications for user feedback. It returns the `toast` function exported by [sonner](https://sonner.emilkowal.ski/toast), with the [defaults](#defaults) below for errors and toasts that carry an action. The built-in layouts (`SidebarLayout`, `GlobalHeaderLayout`) already render the toaster, so no provider setup is needed.

## Signature

Expand All @@ -25,6 +25,44 @@ toast.promise(promise, { loading, success, error });
toast.dismiss(id?);
```

## Defaults

The toaster uses sonner's defaults: bottom right (full width at the bottom at 600px and below), up to three toasts visible, 4 seconds per toast. `useToast` changes two of sonner's per-toast defaults so that a message the user must act on does not disappear on its own:

| Call | `duration` | `closeButton` |
| ----------------------------------------------------------------- | ---------- | ------------- |
| `toast.error(...)`, and the error state of `toast.promise(...)` | `Infinity` | `true` |
| Any call with an `action` (`toast(...)`, `toast.success(...)`, …) | `Infinity` | `true` |
| Everything else, including `toast.custom(...)` | sonner's | sonner's |

An option passed to the call wins over these defaults:

```typescript
toast.error("Retrying in 5s", { duration: 5000 }); // closes after 5 seconds
toast.error("Failed to save", { closeButton: false }); // stays; swipe, or Escape while it has focus, dismisses it
```

For `toast.promise`, a `duration` or `closeButton` on the call applies to the error state, and an `error` result object (`{ message, duration, closeButton, ... }`) wins over both. An `action` on the call is shown in the loading and success states, so those states get the action defaults too.

A toast with `dismissible: false` keeps sonner's defaults (no close button, closes after 4 seconds): the user cannot close it, so `useToast` does not keep it open. If the caller closes it with `toast.dismiss(id)`, pass `duration: Infinity`.

Because these toasts stay, an error that can fire again for the same operation (a retry, a repeated save, one per rejected edit) stacks up a toast for each call. Give the call a stable `id` so the new toast replaces the previous one: `toast.error(message, { id: "save-error" })`.

A call without an `action` that updates an existing toast by `id`, such as `toast.success("Saved", { id })` after `toast.error`, resets `duration` and `closeButton` to sonner's defaults unless it passes its own, so the updated toast closes by itself.

An app changes these defaults with the [`toastDefaults`](../components/app-shell.md#toastdefaults) prop of `AppShell`. A field set there replaces that field only; fields and kinds left out keep the default:

```tsx
// Errors close after 4 seconds without a close button, as before 1.21.0;
// toasts with an action still stay.
<AppShell toastDefaults={{ error: { duration: 4000, closeButton: false } }} modules={modules} />

// Errors close after 10 seconds and keep the close button; the action default is unchanged.
<AppShell toastDefaults={{ error: { duration: 10_000 } }} modules={modules} />
```

These defaults live in `useToast`. A `toast` imported from `sonner` directly does not get them.

## Parameters

### ExternalToast
Expand Down Expand Up @@ -73,6 +111,7 @@ function DeleteButton() {
try {
await deleteItem();
} catch (error) {
// Stays until the user closes it (see Defaults)
toast.error(`Failed to delete: ${(error as Error).message}`);
}
};
Expand All @@ -81,6 +120,25 @@ function DeleteButton() {
}
```

### Toast with an Action

A toast with an `action` stays until the user closes it. Do not make it the only way to do something: if the toast offers Undo, the page offers a way back too.

```typescript
function ArchiveButton({ item }: { item: Item }) {
const toast = useToast();

const handleArchive = async () => {
await archiveItem(item.id);
toast(`${item.name} archived`, {
action: { label: "Undo", onClick: () => restoreItem(item.id) },
});
};

return <button onClick={handleArchive}>Archive</button>;
}
```

### Custom Duration

<!-- example: custom-duration -->
Expand Down
12 changes: 8 additions & 4 deletions docs-src/patterns/interaction-toast.docs.outline.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,12 +40,16 @@ dont:

## Constraints

- Toast renders as a top-right overlay; mobile (<1024) anchors to bottom-center
- Stack max one visible at a time; replace prior toast on new emission
- Success auto-dismisses after 3s; Error is sticky (no auto-dismiss)
- Toasts render at the bottom right. At 600px and below they span the bottom of the viewport
- Up to three stay visible; older ones collapse behind the newest and leave as new ones arrive
- Success, info and plain toasts close by themselves after 4s
- Error toasts, and any toast with an `action`, stay until the user closes them and show a close button. `useToast` sets this; a `duration` or `closeButton` passed to the call wins
- An error that can fire again for the same operation (a retry, a repeated save, one per rejected edit) passes a stable `id`, so the new toast replaces the previous one instead of stacking another toast the user has to close
- Never make a toast the only way to do something. If a toast offers Undo, the page offers a way back too. While a dialog or sheet is open, the keyboard reaches a toast only through sonner's hotkey (Alt+T)

## Anti-patterns

- Toast on every navigation — creates noise; reserve for mutation feedback
- More than one toast stacking — replace, don't accumulate
- One toast per item in a bulk operation — one toast that sums up the result
- An Undo or Retry that exists only in the toast — the page needs the same way back
- Blocking the UI on a toast — toasts are non-modal by definition
Loading
Loading