Customize the drop-in

Make the button and sheet match your app. Everything here is optional, and most of it is set once.

These options need SDK 0.5 or later.

Where it goes

React Native
<MealioProvider
  publishableKey="pk_live_..."
  getSessionToken={getSessionToken}
  theme={{ accent: '#7A2E12', radius: 10 }}
  darkTheme={{ accent: '#F0A070' }}
  colorScheme="auto"
  strings={{ done: 'Listo', total: 'Total' }}
  formatMoney={(n) => new Intl.NumberFormat('es-MX', { style: 'currency', currency: 'MXN' }).format(n)}
  sheet={{ showTotal: true, height: 'full', logo: require('./logo.png') }}
>
iOS
MealioCart.configure(publishableKey: "pk_live_...", sessionTokenProvider: getToken,
                     theme: myTheme, darkTheme: MealioDarkTheme(accent: .orange), colorScheme: .auto,
                     strings: [.done: "Listo"], formatMoney: { String(format: "$%.2f", $0) },
                     sheet: MealioSheetOptions(showTotal: true, height: .full, logo: Image("logo")))
Android
MealioThemeProvider(
    theme = myTheme, darkTheme = MealioDarkTheme(accent = Color(0xFFF0A070)),
    colorScheme = MealioColorScheme.AUTO, strings = mapOf("done" to "Listo"),
    formatMoney = { "$%.2f".format(it) },
    sheet = MealioSheetOptions(showTotal = true, height = MealioSheetHeight.Full, logo = painterResource(R.drawable.logo)),
) { MyApp() }
Flutter
MealioScope(
  navigatorKey: navigatorKey,
  theme: myTheme, darkTheme: MealioTheme.dark(accent: orange), colorScheme: MealioColorScheme.auto,
  strings: const {'done': 'Listo'}, formatMoney: (n) => '\$${n.toStringAsFixed(2)}',
  sheet: MealioSheetOptions(showTotal: true, height: MealioSheetHeight.full),
  child: MyApp(),
)

Text and language

Every word in the sheet has a key, so you can change one line or translate them all. Keys you leave out keep their default. Placeholders like {store} are filled in for you, and a key ending _one or _other is the singular or plural of the same message.

ts
strings={{
  titleList: 'Tu lista de {store}',
  addItems_one: 'Agregar 1 artículo a {store}',
  addItems_other: 'Agregar {count} artículos a {store}',
}}

The full list is in protocol/strings.json in the SDK repo. The "Cart by Mealio" line stays as it is.

Dark mode

The sheet is light unless you say otherwise. Set the color scheme to auto to follow the phone, or dark to always use dark. Without a dark theme of your own, Mealio's default dark colors are used. Your radius and font carry over.

The button

VariantLooks like
solidThe full button. This is the default.
outlineA clear button with an accent border.
compactA small button for recipe cards. Reads "Add to cart".
iconA round cart button with no words on screen.

Or draw your own and keep the whole flow, including the sign-in check that runs ahead of the tap.

React Native
<MealioCartButton recipe={recipe} variant="compact" />

<MealioCartButton recipe={recipe} renderButton={({ onPress, disabled, label }) => (
  <MyButton title={label} onPress={onPress} disabled={disabled} />
)} />
iOS
MealioCartButton(recipe: recipe, variant: .compact)

MealioCartButton(recipe: recipe) { action, disabled, label in
    MyButton(title: label, action: action).disabled(disabled)
}
Android
MealioCartButton(recipe = recipe, variant = MealioButtonVariant.COMPACT)

MealioCartButton(recipe = recipe, button = { onClick, enabled, label ->
    MyButton(label, onClick, enabled)
})
Flutter
MealioCartButton(recipe: recipe, variant: MealioButtonVariant.compact)

MealioCartButton(recipe: recipe, builder: (context, button) =>
    MyButton(button.label, onPressed: button.onPressed))

Recipe details

These go on the recipe you pass in, on every SDK.

ts
{
  id: 'chicken-tinga',
  title: 'Chicken Tinga',
  photoUrl: 'https://cdn.example.com/tinga.jpg',
  servings: 4,        // what the recipe feeds as written
  makeServings: 8,    // what the user is cooking for
  ingredients: [
    { name: 'chicken thighs', amount: 2, unit: 'lb' },
    { name: 'canned tomatoes', quantity: 2 },
    { name: 'salt', pantry: true },
    { name: 'cilantro', optional: true },
  ],
}
FieldWhat it does
servingsWith makeServings, scales weights and any quantity you set, up to 10 times either way. A line with no quantity stays at one package, so doubling a recipe does not buy two jars of salt.
pantrySomething most kitchens have. The item starts unchecked, and the user can still check it.
optionalThe recipe works without it. Starts unchecked too.
photoUrlAn https image. The sheet shows up to three at the top.

When recipes share an ingredient, it starts checked if any of them needs it.

The sheet

OptionWhat it does
showTotalSet it to false to hide the total and the done screen prices. Options keep their own prices.
heightauto, full, or a share of the screen from 0.5 to 1.
logoYour logo at the top of the sheet.

If any item has no price, no total shows, whatever you set here.

Limit the stores

In the dashboard, each app has a Choose stores button. Mealio enforces the list on the server, so you can change it without shipping an update. Users only see those stores. If someone's saved store is not on the list, they pick from the ones that are, and their saved store stays for your other apps.

Passing a store your app does not offer makes the sheet show the picker. On your own screens, prepareCart fails with store_not_allowed.

Limit carts

Each app has a Set limits button in the dashboard. Mealio enforces these on the server.

LimitWhat it doesDefault
Monthly cart capA ceiling on completed carts, so a viral recipe or a bug cannot run up your bill. We email you at 80% and at the cap. Carts already running can finish.No cap
Carts per user, per hourStops one user looping. Up to 20.15
Carts per user, per dayThe same, across a day. Up to 60.30

Past a limit, new carts fail with cart_cap_reached or too_many_carts, and the sheet tells the user to try later. The defaults apply to live apps. A sandbox app allows 60 carts per user an hour and 300 a day, so a test that loops still stops before it hammers a real store. Each limit stands on its own: set only the hourly one on a sandbox app and the daily one stays at 300, and the other way round. The dashboard's Limits line shows the numbers in force, defaults included.

Limit carts by your own plans

For rules like "free users get 3 carts a month", check on your own server before you create a session. With no session there is no cart, and your app can show its upgrade screen.

Node
const used = await countCartsThisMonth(user.id);
if (user.plan === 'free' && used >= 3) {
  return res.status(403).json({ error: 'upgrade_required' });
}
// Otherwise create the Mealio session as normal.

Track the sheet

Set onEvent once, next to your theme, and every step reaches your analytics. Nothing is sent to Mealio.

React Native
<MealioProvider onEvent={(e) => analytics.track('mealio_' + e.type, e)} ... />
EventWhenCarries
sheet_openedThe sheet opens.recipes
store_pickedThe user picks a store.store
location_askedA Kroger family store asks which location.store
signin_shownThe store sign-in appears.store
list_shownThe product list is ready.store, items
item_uncheckedThe user leaves an item out.key
item_checkedThe user puts one back.key
add_startedThe user taps add.items
cart_addedThe store has the items.store, added, failed
errorSomething failed.code, step
sheet_closedThe sheet closes.step, added

The step on sheet_closed is where the user left, so counting by step shows where people drop off.

The done screen

Add a line of your own, and a button that takes people back into your app. It closes the sheet first.

React Native
<MealioCartButton
  recipe={recipe}
  doneMessage="Enjoy your meal!"
  doneAction={{ label: 'Back to meal plan', onPress: (result) => navigate('Plan') }}
/>

On iOS and Android use doneMessage with MealioDoneAction. On Flutter, doneAction: MealioDoneAction(label: ..., onPress: ...).