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 authentication enabled and the color swatches appear. The SDK handles fetching, saving, and asking the user for permission.

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 includeAuth and authRedirectUrl. The reader must be inside an auth-enabled provider. Without one, the highlight color row never renders and no highlight requests are made.

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. The SDK handles the entire round-trip back to your authRedirectUrl.

If the sign-in redirect fails or returns your users to the wrong place, confirm that the URL you pass as authRedirectUrl is registered as a redirect URL for your app in your YouVersion Platform app settings.

Setup

Install the SDK

npm install @youversion/platform-react-ui

Add an auth-enabled provider

Highlights need authentication, so includeAuth and authRedirectUrl are both required. Mount BibleReader anywhere inside that provider:


App.tsx
import { YouVersionProvider, BibleReader } from "@youversion/platform-react-ui";

export default function App() {
  return (
    <YouVersionProvider
      appKey="YOUR_APP_KEY"
      includeAuth={true}
      authRedirectUrl="http://localhost:5173"
    >
      <div style={{ height: "100svh" }}>
        <BibleReader.Root
          defaultBook="JHN"
          defaultChapter="3"
          defaultVersionId={3034}
        >
          <BibleReader.Content />
          <BibleReader.Toolbar />
        </BibleReader.Root>
      </div>
    </YouVersionProvider>
  );
}

Verify it works

Run your app and select a verse. The verse action popover opens with a row of color swatches alongside Copy and Share. Tap one. 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 includeAuth, the color row never renders 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 verse action popover, and a row of color swatches appears in it alongside Copy and Share. In dark mode the color may be modified for better legibility.

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.
Signed out. The sign-in dialog opens. Confirming starts a full-page redirect to YouVersion, and the color the user tapped is applied for them when they land back on your authRedirectUrl.
Signed in without the highlights permission. The permission dialog opens instead. The redirect works the same way: the user grants access on YouVersion, returns to your authRedirectUrl, and the pending highlight is applied.

In every case the SDK holds the pending highlight across the redirect, so a user never loses the color they tapped.

The dialogs

Both dialogs are rendered by the SDK. Because tapping a color can send a user to another page, each dialog explains what is about to happen and gives the user a chance to cancel. Neither dialog can be customized or suppressed through a BibleReader prop.

The sign-in dialog 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 dialog 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.

The sign-in dialog names your app using the appName you pass to YouVersionProvider, falling back to a generic name when you don't set one. The provider's signInPromptMessage prop adds an optional line above the body text.

Clearing a highlight

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

Signing out

Highlights are not cached. When the user signs out, all highlighting is removed immediately from display.

Troubleshooting

Most highlight problems fail quietly, with nothing rendered, nothing thrown, and nothing sent to the network.

Symptom	Cause	Fix
No color row in the popover, and no errors. Copy and Share still work.	The surrounding `YouVersionProvider` has no `includeAuth`. Highlights require an auth-enabled provider.	Add `includeAuth` and `authRedirectUrl` to the provider.
Tapping a color opens a dialog instead of highlighting the verse.	The user is signed out, or is signed in without the `highlights` permission.	This is expected. The dialog collects what is missing, and the highlight is applied when the user lands back on your `authRedirectUrl`.
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

Last modified on August 3, 2026

Theming Migration from Legacy Authentication