Notifications¶

Overview¶

Pebbl uses two notification styles: toasts and banners. Each has distinct formatting rules to match its visual weight and purpose.

Toasts¶

Toasts are brief, non-intrusive notifications that appear temporarily. They confirm completed actions or surface lightweight errors.

Punctuation: No trailing punctuation.

Tone: Short, past-tense confirmation of what happened.

Updated income
Category renamed
Connection lost
Linked Chase

When to use: After a successful mutation, or for transient errors that do not require the user to take action.

Banners¶

Banners are prominent, full-width notifications that appear at the top of the page. They auto-dismiss after 5 seconds by default, though error banners persist until the user clicks them. Banners are used for errors, confirmations, and important state changes that warrant more visual weight than a toast.

Punctuation: Use trailing punctuation (periods).

Tone: Complete sentences that describe what happened or what went wrong.

Failed to update income.
The requested income item does not exist or could not be found.
Successfully logged out your desktop device.

When to use: For errors returned by handleError (which always renders banners), not-found states, or important confirmations like device logouts.

handleError fallback messages¶

The handleError hook always renders error banners. Its fallbackMessage must include trailing punctuation since the message appears inside a banner.

// Correct
handleError(error, {
  fallbackMessage: "Failed to update income.",
});

// Incorrect
handleError(error, {
  fallbackMessage: "Failed to update income",
});

Shared error constants¶

When the same error concept appears as both a toast and a banner fallback, define two constants rather than reusing one with inconsistent punctuation.

const ERROR_TOAST_MESSAGE = "Failed to update";
const ERROR_BANNER_MESSAGE = "Failed to update.";

Rules¶

• Toast messages never end with a period, question mark, or exclamation point.
• Banner descriptions always end with a period.
• Banner headers are short labels (e.g., "Error", "Not found", "Logged out") and do not use trailing punctuation.
• Never share a single string constant between a toast call and a handleError fallback.