useMessages

The useMessages hook manages the checkout’s notification messages (alerts, confirmations, errors). It lets you add, remove, and clear messages from any custom component; the template renders them.

Let your agent build it. The Ollie Shop skill ships with projects created by npx create-ollie-shop and knows the message types and when surfacing one beats failing silently.

Prompt

Show an error message when my validation fails.

Don’t have the skill yet? Install it.

Import

import { useMessages } from '@ollie-shop/sdk';

Usage

const { messages, addMessage, removeMessage, clearAll } = useMessages();

// Add a new message
addMessage({
  type: 'success',
  content: 'Order completed successfully!'
});

// Remove a specific message
removeMessage(messageId);

// Clear all messages
clearAll();

Return Value

Property	Type	Description
`messages`	`Message[]`	The messages currently shown
`addMessage`	`(input: AddMessageInput) => void`	Adds a message. Pass either `content` or a `ServerError` as `error`
`removeMessage`	`(messageId: string) => void`	Removes one message by id
`clearAll`	`() => void`	Removes every message

Message

Property	Type	Description
`id`	`string`	Generated automatically when the message is added
`type`	`"info" \| "success" \| "warning" \| "error"`	Decides the color and the icon
`content`	`React.ReactNode`	The body. A string or any React node
`title`	`React.ReactNode \| undefined`	An optional title

AddMessageInput

type is required, title is optional, and exactly one of these two:

content: the text or node to show.
error: a ServerError (the object useCheckoutAction gives onError). The hook resolves it to the store’s translated message by looking up, in order, the platform error code, the error code, the error group, and finally a generic “unknown error” text. That way the shopper sees the same wording the native components use.

How the stack behaves

At most three messages are shown at a time. When a fourth arrives, the oldest message with the lowest priority is dropped (error outranks warning, then info, then success).
A message with the same type and text as one already shown is ignored, so retrying an action does not pile up duplicates.
Messages are not dismissed automatically. They stay until you call removeMessage(id) or clearAll(), or the template’s own rendering removes them.

Example

The example below shows two different messages, a success and an error

Desktop	Mobile

To achieve the result in the example above:

import { useMessages } from '@ollie-shop/sdk';

function NotificationSystem() {
  const { messages, addMessage, clearAll } = useMessages();

  const handleSuccess = () => {
    addMessage({
      type: 'success',
      title: 'Order Placed',
      content: 'Your order has been successfully placed.',
    });
  };

  const handleError = () => {
    addMessage({
      type: 'error',
      content: 'Unable to process your request. Please try again.',
    });
  };

  return (
    <div>
      <button onClick={handleSuccess}>Place Order</button>
      <button onClick={handleError}>Test Error</button>

      {messages.length > 0 && (
        <button onClick={clearAll}>Clear All Messages</button>
      )}
    </div>
  );
}

Examples per action

addMessage(input)

// Direct message
addMessage({
  type: 'success',
  title: 'Order Placed',
  content: 'Your order has been successfully placed.'
});

// Resolved from a ServerError, typically inside an action's onError handler.
const { execute } = useCheckoutAction('UPDATE_COUPONS', {
  onError: ({ serverError }) => {
    if (serverError) addMessage({ type: 'error', error: serverError });
  },
});

removeMessage(messageId)

removeMessage(messages[0].id);

clearAll()

clearAll();

useCheckoutAction: the source of the ServerError objects addMessage can resolve
useNavigation: pair a blocked step with a message explaining why

Overview

Start Here

AI Coding Agents

Core Concepts

Customization

Ollie Studio

Functions

CLI Reference

Ollie SDK

Analytics & Scripts

Tools & Tips

Product updates

Import

Usage

Return Value

Message

AddMessageInput

How the stack behaves

Example

Examples per action

addMessage(input)

removeMessage(messageId)

clearAll()

​Import

​Usage

​Return Value

​Message

​AddMessageInput

​How the stack behaves

​Example

​Examples per action

​addMessage(input)

​removeMessage(messageId)

​clearAll()

​Related

Import

Usage

Return Value

Message

AddMessageInput

How the stack behaves

Example

Examples per action

addMessage(input)

removeMessage(messageId)

clearAll()

Related