- What is Toast?
- How does it work?
- 3.X Breaking Changes
- Client Install
- Courier Integration
- Client Setup
- Using Courier's API
- Props
- Theme
- Using Hook
Toast aims to be the easiest way to create in-app notifications. With a simple integration and straight forward API we make it easy for anyone to integrate fast.
Toast is a buzz word for a notification that happens in-app and slides in or pops up. The appearance is usually that of a rectangle in the top right of an application.
There are two ways to use this library:
- With Courier as a transport provider
- A standalone toast interface
You can use the Courier Push integration to create a notification through the designer and send a notification to a specific channel/event from an API request. This will trigger the toast to show wherever the client is running and listening for that same channel/event.
A channel/event combination is simply a stream on which a particular client is listening for toast notifications. A client must be subscribed to a channel and event in order to receive a notification.
We've implemented a new API which has a little bit different format for the messages that come through the websocket and this in turn means some of the function calls and hooks have a different API.
The format of the message has changd, so if you have any code that utilizes any of the following you will need to update:
- Interacting with
useToast
- Intercepting messages with Courier Provider prop onMessage
- Implemented
renderMessage
orrenderAction
This is a contrived example of the changes:
Note we are utilized our new elemental standard:
interface OldMessage {
title: string;
body: string;
blocks: Array<TextBlock | ActionBlock>;
}
interface NewMessage {
title: string;
preview: string;
actions: Array<ActionElement>;
}
The new toast component also does not show any buttons. The actual toast is clickable and will highlight a background color to let users know it has a link associated with it.
You can revert and use the 2.X releases to prevent having the above breaking changes. You will need both @trycourier/react-toast
and @trycourier/react-provider
to be on the same 2.X version.
- theme.message.actionBlock -> deprecated
- the entire message is now clickable
- theme.message.textBlock -> theme.message.textElement
-
theme.message.clickableContainer
: when a message has an action href, we now make the entire message clickable instead of rendering an explicit button. this theme property allows access to this component.theme.message.container
will still apply to this component but if you want to target the clickableContainer separatly you can targettheme.message.clickableContainer
which will be ananchor
element instead of adiv
;
yarn add @trycourier/react-toast
We will need to install the Courier Push Integration to trigger a toast from an API request. Make sure to copy the Client Key from the integration page after installing.
Now that you have a notification ready to be sent lets setup the client to listen for the notification and invoke it when triggered. Pass your userId and clientKey into your CourierProvider and we will handle all of the network connections
import { CourierProvider } from "@trycourier/react-provider";
import { Toast } from "@trycourier/react-toast";
const App: React.FunctionComponent = () => {
return (
<CourierProvider userId={USER_ID} clientKey={CLIENT_KEY}>
<Toast />
</CourierProvider>
);
};
Now that we have the Courier Provider installed and we have our React application listening to messages, we can trigger a send to the Courier API.
import { CourierClient } from "@trycourier/courier";
const courier = CourierClient({
authorizationToken: process.env.COURIER_AUTH_TOKEN,
});
await courier.send({
message: {
to: {
user_id: "USER_ID",
},
content: {
title: "Hello World",
body: "{{foo}}",
},
data: {
foo: "bar",
},
},
});
If you want to use the template designer an api call would instead look like the following:
import { CourierClient } from "@trycourier/courier";
const courier = CourierClient({
authorizationToken: process.env.COURIER_AUTH_TOKEN,
});
await courier.send({
message: {
to: {
user_id: "USER_ID",
},
template: "TEMPLATE_ID",
data: {
foo: "bar",
},
},
});
interface ToastProps {
// Number in ms for Toast to auto close
// Set as `false` to disable auto close
autoClose?: false | number;
// Default icon if no icon is present in message
defaultIcon?: string | false;
// Hide the progress bar
hideProgressBar?: boolean;
onClick?: MouseEventHandler<Element>;
// Toast positioning when triggered
position?: "top-left" | "top-right" | "top-center" | "bottom-left" | "bottom-right" | "bottom-center";
role?: "alert" | "status";
theme?: Theme;
// Animation when the Toast is displayed
transition?: "bounce" | "slide" | "zoom";
}
interface ITheme {
body?: CSSObject;
root?: CSSObject;
toast?: CSSObject;
dismiss?: CSSObject;
message?: {
clickableContainer?: CSSObject;
container?: CSSObject;
contents?: CSSObject;
icon?: CSSObject;
textElement?: CSSObject;
title?: CSSObject;
};
progressBar?: CSSObject;
};
The style configuration objects should be defined with Style Objects. Style Objects can accept CSS Pseudo selectors for more advanced styling. See here for more info or check below for advanced usage examples.
Styles will be merged with defaults so if you do not explicitly override a style it will not be changed.
If you do not want to use Courier Push to trigger a toast notification then you can always invoke the toast locally with the useToast
hook. Below is an example creating a notification from the client rather than creating it from a transport. Do not forget to wrap this component with a CourierProvider
somewhere up the component hierarchy chain.
import { CourierProvider } from "@trycourier/react-provider";
import { Toast, useToast } from "@trycourier/react-toast";
const MyComponent: React.FunctionComponent = () => {
//We can access this because the parent is a `CourierProvider`
const [toast] = useToast();
return (
<button onClick={() => toast("You just made a notification 🎉")}></button>
);
};
const App: React.FunctionComponent = () => {
return (
<CourierProvider userId={USER_ID} clientKey={CLIENT_KEY}>
<Toast />
<MyComponent />
</CourierProvider>
);
};