Skip to content

Latest commit

 

History

History
302 lines (215 loc) · 6.25 KB

README.md

File metadata and controls

302 lines (215 loc) · 6.25 KB
Raw

🍞 burnt

Cross-platform toasts for React Native, powered by native elements.

Now with Android, iOS & Web Support.

Alerts

Simulator.-.iPhone.13.Pro.Max.-.16.November.2022.3.mp4

...and Toasts

Simulator.-.iPhone.13.Pro.Max.-.18.November.2022.mp4

...and Web Support

burnt-example.-.8.May.2023.mp4

Context

See this Twitter thread.

What

This is a library with a toast and alert method for showing ephemeral UI.

On iOS, it wraps SPIndicator and AlertKit.

On Android, it wraps ToastAndroid from react-native. Burnt.alert() falls back to Burnt.toast() on Android. This may change in a future version.

On Web, it wraps sonner by Emil Kowalski.

Burnt works with both the old & new architectures. It's built on top of JSI, thanks to Expo's new module system.

Features

  • Simple, imperative toast that uses native components under the hood, rather than using React state with JS-based UI.
  • Animated icons
  • iOS App Store-like alert popups
  • Overlays on top of native iOS modals
  • Loading alerts

Modals

Displaying toasts on top of modals has always been an issue in React Native. With Burnt, this works out of the box.

Simulator.-.iPhone.13.Pro.Max.-.17.November.2022.mp4

Usage

import * as Burnt from "burnt";

Burnt.toast({
  title: "Burnt installed.",
  preset: "done",
  message: "See your downloads.",
});

You can also Burnt.alert() and Burnt.dismissAllAlerts().

TODO

  • iOS support
  • Android support
  • Custom iOS icons
  • Web support

Installation

yarn add burnt

Expo

Burnt likely requires Expo SDK 46+.

npx expo install burnt expo-build-properties

Add the expo-build-properties plugin to your app.json/app.config.js, setting the deployment target to 13.0 (or higher):

export default {
  plugins: [
    [
      "expo-build-properties",
      {
        ios: {
          deploymentTarget: "13.0",
        },
      },
    ],
  ],
};

Then, you'll need to rebuild your dev client. Burnt will not work in Expo Go.

npx expo prebuild --clean
npx expo run:ios

The config plugin ensures that your iOS app has at least iOS 13 as a deployment target, which is required for Burnt (as well as Expo SDK 47+).

Web Support

To enable Web support, you need to add the <Toaster /> to the root of your app. If you're using Next.js, add this into your _app.tsx component.

// _app.tsx
import { Toaster } from "burnt/web";

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <Toaster position='bottom-right' />
    </>
  );
}

If you're using Next.js, add burnt to your transpilePackages in next.config.js.

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: [
    // Your other packages here
    "burnt"
  ]
}

To configure your Toaster, please reference the sonner docs.

Expo Web

If you're using Expo Web, you'll need to add the following to your metro.config.js file:

// Learn more https://docs.expo.io/guides/customizing-metro
const { getDefaultConfig } = require("expo/metro-config");

const config = getDefaultConfig(__dirname);

// --- burnt ---
config.resolver.sourceExts.push("mjs");
config.resolver.sourceExts.push("cjs");
// --- end burnt ---

module.exports = config;

Plain React Native

pod install

Solito

cd applications/app
expo install burnt expo-build-properties
npx expo prebuild --clean
npx expo run:ios
cd ../..
yarn

Be sure to also follow the expo instructions and web instructions.

API

toast

Simulator.-.iPhone.13.Pro.Max.-.16.November.2022.mp4

toast(options): Promise<void>

Burnt.toast({
  title: "Congrats!", // required

  preset: "done", // or "error", "none", "custom"

  message: "", // optional

  haptic: "none", // or "success", "warning", "error"

  duration: 2, // duration in seconds

  shouldDismissByDrag: true,

  from: "bottom", // "top" or "bottom"

  // optionally customize layout
  layout: {
    iconSize: {
      height: 24,
      width: 24,
    },
  },
  icon: {
    ios: {
      // SF Symbol. For a full list, see https://developer.apple.com/sf-symbols/.
      name: "checkmark.seal",
      color: "#1D9BF0",
    },
    web: <Icon />,
  },
});

alert

Simulator.-.iPhone.13.Pro.Max.-.16.November.2022.2.mp4

The API changed since recording this video. It now uses object syntax.

alert(options): Promise<void>

import * as Burnt from "burnt";

export const alert = () => {
  Burnt.alert({
    title: "Congrats!", // required

    preset: "done", // or "error", "heart", "custom"

    message: "", // optional

    duration: 2, // duration in seconds

    // optionally customize layout
    layout: {
      iconSize: {
        height: 24,
        width: 24,
      },
    },
    icon: {
      ios: {
        // SF Symbol. For a full list, see https://developer.apple.com/sf-symbols/.
        name: "checkmark.seal",
        color: "#1D9BF0",
      },
      web: <Icon />,
    },
  });
};

On Web, this will display a regular toast. This may change in the future.

dismissAllAlerts()

Does what you think it does! In the future, I'll allow async spinners for promises, and it'll be useful then.

Contribute

yarn build
cd example
yarn
npx expo run:ios # do this again whenever you change native code

You can edit the iOS files in ios/, and then update the JS accordingly in src.

Thanks

Special thanks to Tomasz Sapeta for offering help along the way.

Expo Modules made this so easy to build, and all with Swift – no Objective C. It's my first time writing Swift, and it was truly a breeze.