Guides

Highlights

BibleReader can let your readers highlight verses. A reader selects a verse, taps a color, and the highlight is saved to their YouVersion account. These are the same highlights they see everywhere else in the YouVersion Bible App.

There is nothing to switch on. Highlights are part of BibleReader: put the reader inside a YouVersionProvider with an auth config that includes permissions: ['highlights'], and the color swatches appear in the native verse action sheet. The SDK handles fetching, saving, and asking the user for permission.

Highlights require version 1.2.0 or later of @youversion/platform-react-native-expo-ui and @youversion/platform-react-native-expo-core. Earlier versions do not show color swatches in the verse action sheet.

Requirements

Highlights are stored on the user's YouVersion account, so the reader needs authentication in place. Two things are required:

An App Key. Sign up at platform.youversion.com to get one.
A YouVersionProvider with an auth config that sets redirectUri, scopes, and permissions: ['highlights']. The reader must be inside that provider. Without that auth setup, color swatches do not appear in the verse action sheet and the SDK cannot request the highlights grant or save highlights to the user account.

A signed-in user is not a prerequisite. The first time a user taps a color, the reader asks for whatever is missing: sign-in first, then the highlights permission. Sign-in and consent run in an in-app browser session (expo-web-browser openAuthSessionAsync) and return through your app scheme and redirectUri.

Register your scheme and callback URI before you enable Highlights. See Authentication for app.json scheme setup, Platform console Callback URI registration, and Linking.createURL("callback").

Setup

Install the SDK packages

Highlights ship with BibleReader. Install both UI and core packages so TypeScript resolves auth and permission types:
```
expo
npx expo install @youversion/platform-react-native-expo-ui@1.2.0 @youversion/platform-react-native-expo-core@1.2.0
```

Add an auth-enabled provider

Pass permissions: ['highlights'] on the provider auth config alongside redirectUri and scopes. Put highlights in permissions, not scopes. Wrap the provider in GestureHandlerRootView, then mount BibleReader anywhere inside:


app/_layout.tsx
import { YouVersionProvider } from "@youversion/platform-react-native-expo-ui";
import * as Linking from "expo-linking";
import { Stack } from "expo-router";
import { GestureHandlerRootView } from "react-native-gesture-handler";

export default function RootLayout() {
  const appKey = process.env.EXPO_PUBLIC_YOUVERSION_APP_KEY;
  const redirectUri = Linking.createURL("callback");

  if (!appKey) return null;

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <YouVersionProvider
        appKey={appKey}
        auth={{
          redirectUri,
          scopes: ["profile", "email"],
          permissions: ["highlights"],
        }}
      >
        <Stack screenOptions={{ headerShown: false }} />
      </YouVersionProvider>
    </GestureHandlerRootView>
  );
}


app/(tabs)/reader.tsx
import { BibleReader } from "@youversion/platform-react-native-expo-ui";
import { View } from "react-native";

export default function ReaderScreen() {
  return (
    <View style={{ flex: 1 }}>
      <BibleReader defaultVersionId={3034} />
    </View>
  );
}

Verify it works

Run a development build, select a verse, and confirm the native verse action sheet shows color swatches alongside Copy and Share. If you see Copy and Share but no color swatches, check that the provider has an auth config with permissions: ['highlights'] and that Authentication setup is complete. Tap a swatch. If you are signed in and have already granted the highlights permission, the verse is highlighted immediately.

The provider is what turns highlights on. If the surrounding YouVersionProvider has no auth config, or auth omits permissions: ['highlights'], the color swatches never appear in the verse action sheet and no highlight requests are made. Nothing errors, and Copy, Share, and verse selection all keep working, so this is easy to miss.

What your users see

Selecting a verse opens the native verse action sheet. Color swatches appear in it alongside Copy and Share. In dark mode the SDK may adjust a color for legibility in the reader.

What happens when a user taps a color depends on what they have already granted:

Signed in, highlights permission granted. The verse is highlighted immediately and saved to their YouVersion account. Highlights they made in the YouVersion Bible App also appear here while they are signed in.
Signed out. A sign-in sheet opens. Continuing starts an in-app browser session to YouVersion. When the session returns through your app scheme and redirectUri, the color the user tapped is applied.
Signed in without the highlights permission. A permission sheet opens instead. The in-app browser flow works the same way: the user grants access on YouVersion, returns to your app, and the pending highlight is applied.

In every case the SDK holds the pending highlight in memory across the auth session, so a user never loses the color they tapped for the same chapter.

While signed in, the SDK keeps a light local cache of highlights for the current reading session. Signing out clears that local cache and any queued writes along with the session.

The sheets

Both sheets are rendered by the SDK. Because tapping a color can send a user through an in-app browser session, each sheet explains what is about to happen and gives the user a chance to cancel. Neither sheet can be customized or suppressed through a BibleReader prop.

The sign-in sheet opens when the user is signed out. It introduces your app, tells the user it wants to connect to their YouVersion Bible App account, and asks whether to continue.
The permission sheet opens when the user is signed in but has not granted the highlights permission. It asks the user to let your app save highlights to their YouVersion account.

Clearing a highlight

Once a verse is highlighted, that color shows a checkmark in the action sheet. Tapping it again removes the highlight. There is no separate clear control.

Signing out

When the user signs out, highlighting is removed from display and the SDK clears its local highlight cache and queue for that session.

Troubleshooting

Symptom	Cause	Fix
No color swatches in the verse action sheet, and no errors. Copy and Share still work.	The surrounding `YouVersionProvider` has no `auth` config, or `auth` omits `permissions: ['highlights']`.	Pass `auth={{ redirectUri, scopes, permissions: ['highlights'] }}` to the provider and confirm Authentication setup.
Tapping a color opens a sheet instead of highlighting the verse.	The user is signed out, or is signed in without the `highlights` permission.	This is expected. Complete sign-in or grant the permission in the in-app browser session; the pending highlight applies when the session returns.
Thrown error: "YouVersion context not found."	`BibleReader` is mounted outside `YouVersionProvider`.	Wrap the reader, and everything else that uses the SDK, in a single `YouVersionProvider`.

See also: BibleReader, Authentication

Last modified on August 19, 2026