React Native (Expo) SDK

Components

Copy page

All components are imported from @youversion/platform-react-native-expo-ui and must be rendered inside a YouVersionProvider. They read appKey from the provider, so you never pass it to a component directly.

Every component accepts two cross-cutting props:

• theme — "light" | "dark" | "system". Overrides the provider theme for that component. See Theming.
• dom — Expo DOMProps passed to the underlying DOM component (for example dom={{ matchContents: true }} to size the view to its content).

---

Sizing embedded components

BibleCard, VerseOfTheDay, and BibleTextView render inside a WebView and default to matchContents sizing: the component measures its content and sizes itself to fit, like a normal React Native view. No configuration is needed for the common case — for example a card inside a ScrollView.

To give one of these components a fixed size or have it participate in flex layout instead, opt out with dom={{ matchContents: false }} and size it yourself (a fixed height, or flex on a wrapper View).

BibleReader is different: it is a full reading surface that fills its container, so let it fill the screen (or a tab) with flex: 1 rather than sizing to content.

---

YouVersionProvider

Required provider that configures the SDK. Wrap your app root with it (inside GestureHandlerRootView). Authentication is optional — see Authentication.

Code
import { YouVersionProvider } from "@youversion/platform-react-native-expo-ui";

<YouVersionProvider appKey="YOUR_APP_KEY" theme="system">
  {/* your app */}
</YouVersionProvider>;

Props:

Prop	Type	Default	Description
appKey	string	required	Your YouVersion Platform App Key.
theme	"light" | "dark" | "system"	"system"	Default theme for all SDK components. "system" follows the OS.
locale	string	device locale	Override the language of the SDK's built-in UI strings. Defaults to the device locale.
auth	{ redirectUri: string; scopes?: AuthScope[] }	—	Enables authentication. See Authentication.
fallback	ReactNode	—	Rendered while the provider initializes.
children	ReactNode	required	Your app.

useYouVersion

Reads the provider's resolved configuration. Useful when you call the HTTP API yourself and need the appKey — see Copyright & Attribution. It throws when used outside a YouVersionProvider.

Code
import { useYouVersion } from "@youversion/platform-react-native-expo-core";

const { appKey, apiHost, installationId } = useYouVersion();

Return value:

Field	Type	Description
appKey	string	The App Key passed to the provider.
apiHost	string	Platform API host. Defaults to api.youversion.com.
installationId	string	Anonymous per-install identifier generated by the SDK.
authRedirectUrl	string | undefined	The auth.redirectUri passed to the provider, or undefined when auth is not configured.

---

BibleTextView

Render a verse or passage with no surrounding card. You control the layout.

Code
import { BibleTextView } from "@youversion/platform-react-native-expo-ui";

<BibleTextView reference="JHN.3.16" versionId={3034} showVerseNumbers />;

Props:

Prop	Type	Default	Description
reference	string	required	USFM reference, e.g. "JHN.3.16" or "PSA.23.1-6".
versionId	number	required	Bible version ID.
fontFamily	string	—	Font family for the passage text.
fontSize	number	—	Font size.
lineHeight	number	—	Line height.
showVerseNumbers	boolean	true	Show verse numbers.
renderNotes	boolean	true	Render footnote markers (tapping opens a native sheet).
onFootnotePress	(data: FootnoteData) => Promise<void>	—	Override the default footnote sheet.
theme	"light" | "dark" | "system"	provider	Theme override.
dom	DOMProps	—	Expo DOM props.

---

BibleCard

A pre-styled card displaying a passage with its reference, text, and automatic copyright attribution. A version picker that opens in a native bottom sheet is built in but hidden by default; pass showVersionPicker to enable it.

Code
import { BibleCard } from "@youversion/platform-react-native-expo-ui";

<BibleCard reference="JHN.3.16" versionId={3034} dom={{ matchContents: true }} />;

Props:

Prop	Type	Default	Description
reference	string	required	USFM reference.
versionId	number	3034	Bible version ID. Seeds the version picker.
defaultVersionId	number	3034	Initial version when used uncontrolled.
showVersionPicker	boolean	false	Show the built-in version picker button. Hidden by default.
onVersionChange	(versionId: number) => void	—	Called when the version changes. Provide with versionId for controlled use.
onVersionPickerPress	(data: BibleVersionPickerPressData) => Promise<void>	—	Override — present your own version picker instead of the built-in sheet. Only fires when the picker is shown (showVersionPicker).
onFootnotePress	(data: FootnoteData) => Promise<void>	—	Override the default footnote sheet.
theme	"light" | "dark" | "system"	provider	Theme override.
dom	DOMProps	—	Expo DOM props.

---

BibleReader

A complete Bible reading experience — passage text plus built-in chapter, version, and reader-settings sheets. Drop it into a tab or full screen.

Code
import { BibleReader } from "@youversion/platform-react-native-expo-ui";

<BibleReader defaultVersionId={3034} />;

BibleReader is stateful: it owns the current book, chapter, and version, persists the reading location across app launches, and coordinates its built-in sheets. Each of book / chapter / version can also be controlled.

Props:

Prop	Type	Default	Description
defaultBook	string	"JHN"	Initial book (3-letter USFM code) when uncontrolled.
book / onBookChange	string / (book: string) => void	—	Controlled book.
defaultChapter	string	"1"	Initial chapter when uncontrolled.
chapter / onChapterChange	string / (chapter: string) => void	—	Controlled chapter.
defaultVersionId	number	3034	Initial version when uncontrolled.
versionId / onVersionChange	number / (versionId: number) => void	—	Controlled version.
showToolbar	boolean	true	Show the toolbar with version/chapter/settings controls.
onChapterPickerPress	(data: BibleChapterPickerPressData) => Promise<void>	—	Override — present your own chapter picker.
onVersionPickerPress	(data: BibleVersionPickerPressData) => Promise<void>	—	Override — present your own version picker.
onFootnotePress	(data: FootnoteData) => Promise<void>	—	Override the default footnote sheet.
backgroundColor	string	—	Override the reader background color.
foregroundColor	string	—	Override the reader text color.
theme	"light" | "dark" | "system"	provider	Theme override.
dom	DOMProps	—	Expo DOM props.

Custom picker flows

To present your own picker UI instead of the built-in sheets, implement onChapterPickerPress or onVersionPickerPress. The matching built-in sheet is suppressed and you receive the current selection:

Code
<BibleReader
  defaultVersionId={3034}
  onVersionPickerPress={async ({ versionId, languageId }) => {
    // present your own version picker
  }}
/>

---

VerseOfTheDay

Display the YouVersion Verse of the Day. Includes automatic attribution.

Code
import { VerseOfTheDay } from "@youversion/platform-react-native-expo-ui";

<VerseOfTheDay versionId={3034} dom={{ matchContents: true }} />;

Props:

Prop	Type	Default	Description
versionId	number	3034	Bible version ID.
dayOfYear	number	today	Day of the year (1–366).
showSunIcon	boolean	true	Show the decorative sun icon.
showBibleAppAttribution	boolean	true	Show the YouVersion Bible App attribution.
showShareButton	boolean	true	Show the share button.
size	"default" | "lg"	"default"	Card size.
theme	"light" | "dark" | "system"	provider	Theme override.
dom	DOMProps	—	Expo DOM props.

---

YouVersionAuthButton

Pre-styled button for YouVersion authentication. Handles sign-in and sign-out via useYVAuth internally — you do not wire up signIn() yourself unless you need a fully custom UI (see Authentication).

Code
import { YouVersionAuthButton } from "@youversion/platform-react-native-expo-ui";

<YouVersionAuthButton mode="auto" background="light" outline />;

Props:

Prop	Type	Default	Description
mode	"signIn" | "signOut" | "auto"	"auto"	"auto" shows sign-in when signed out and sign-out when signed in.
background	"light" | "dark"	"light"	Button color scheme.
outline	boolean	false	Render as an outlined button.
radius	"rounded" | "rectangular"	"rounded"	Corner style.
size	"default" | "short" | "icon"	"default"	"short" uses compact label text; "icon" shows the YouVersion logo only.
text	string	—	Override the default localized button label.

Examples:

Code
// Outlined, dark theme
<YouVersionAuthButton background="dark" outline />

// Always show sign-in
<YouVersionAuthButton mode="signIn" />

// Icon only
<YouVersionAuthButton size="icon" />

---

Theming

Set a default theme on the provider with the theme prop, and override it per component with each component's theme prop.

Value	Behavior
"light"	Light mode.
"dark"	Dark mode.
"system"	Follows the device's OS light/dark setting, live (default).

Code
<YouVersionProvider appKey="YOUR_APP_KEY" theme="system">
  {/* Forces dark styling regardless of the provider/OS theme */}
  <BibleCard reference="JHN.3.16" versionId={3034} theme="dark" />
</YouVersionProvider>

---

Advanced: standalone sheets

BibleReader already manages its own chapter, version, and settings sheets, so most apps never need these. For custom flows, the sheets are exported so you can present them yourself. Each is controlled via isOpen / onClose.

Code
import {
  BibleChapterPickerSheet,
  BibleVersionPickerSheet,
  BibleReaderSettingsSheet,
} from "@youversion/platform-react-native-expo-ui";

BibleVersionPickerSheet

Code
<BibleVersionPickerSheet
  isOpen={open}
  onClose={() => setOpen(false)}
  versionId={versionId}
  onSelect={(versionId) => setVersionId(versionId)}
/>

Prop	Type	Default	Description
isOpen	boolean	required	Whether the sheet is open.
onClose	() => void	required	Called when the sheet should close.
versionId	number	3034	Currently selected version.
onSelect	(versionId: number) => void | Promise<void>	—	Called when a version is selected.
theme	"light" | "dark" | "system"	provider	Theme override.
dom	DOMProps	—	Expo DOM props.

BibleChapterPickerSheet

Code
<BibleChapterPickerSheet
  isOpen={open}
  onClose={() => setOpen(false)}
  book="JHN"
  chapter="1"
  versionId={3034}
  onSelect={({ book, chapter }) => {
    /* ... */
  }}
/>

Prop	Type	Default	Description
isOpen	boolean	required	Whether the sheet is open.
onClose	() => void	required	Called when the sheet should close.
book	string	"JHN"	Currently selected book.
chapter	string	"1"	Currently selected chapter.
versionId	number	3034	Version whose books/chapters to show.
onSelect	(data: BibleChapterPickerSelectData) => void | Promise<void>	—	Called with { book, chapter, versionId }.
theme	"light" | "dark" | "system"	provider	Theme override.
dom	DOMProps	—	Expo DOM props.

BibleReaderSettingsSheet

The reader's font-size and font-family controls.

Prop	Type	Default	Description
isSettingsSheetOpen	boolean	required	Whether the sheet is open.
onClose	() => void	required	Called when the sheet should close.