Skip to main content
Providers are React Context components that manage configuration and state across your application. All data hooks depend on these providers to function correctly.

​
YouVersionProvider

The core provider that configures the SDK and must wrap your entire application.

​
Props

​
appKey
string
required
Your YouVersion Platform API key
​
apiHost
string
default:"api.youversion.com"
The API host URL (rarely needs to be changed)
​
theme
'light' | 'dark' | 'system'
default:"light"
Theme preference for the SDK. When set to 'system', automatically follows the user’s system color scheme preference.
​
includeAuth
boolean
default:false
Enable authentication functionality. When true, must also provide authRedirectUrl.
​
authRedirectUrl
string
OAuth callback URL (required when includeAuth is true)
​
children
ReactNode
required
Your application components

​
Features

  • Automatically generates and manages installation ID
  • Syncs configuration with YouVersionPlatformConfiguration from core package
  • Lazy-loads authentication provider when includeAuth is enabled
  • Automatically resolves system theme preference
  • Listens for system theme changes when theme="system"

​
Usage

import { YouVersionProvider } from '@youversion/platform-react-hooks';

function App() {
  return (
    <YouVersionProvider appKey="your-app-key">
      <YourApp />
    </YouVersionProvider>
  );
}

​
Context Value

The provider exposes the following context value:
​
appKey
string
The API key provided to the provider
​
apiHost
string
The API host URL
​
installationId
string
Auto-generated installation identifier
​
theme
'light' | 'dark'
Resolved theme (never returns 'system', always resolved to actual theme)
​
authEnabled
boolean
Whether authentication is enabled

​
ReaderProvider

Manages Bible reading session state, including current version, book, chapter, and verse.

​
Props

​
currentVersion
BibleVersion
required
Initial Bible version
​
currentBook
BibleBook
required
Initial Bible book
​
currentChapter
BibleChapter
required
Initial chapter
​
currentVerse
BibleVerse | null
required
Initial verse (or null if no specific verse)
​
children
ReactNode
required
Child components

​
Usage

import { ReaderProvider } from '@youversion/platform-react-hooks';

function MyReader({ version, book, chapter }) {
  return (
    <ReaderProvider
      currentVersion={version}
      currentBook={book}
      currentChapter={chapter}
      currentVerse={null}
    >
      <ChapterReader />
      <ChapterNavigation />
    </ReaderProvider>
  );
}

​
Context Value

​
currentVersion
BibleVersion
Current Bible version
​
currentBook
BibleBook
Current Bible book
​
currentChapter
BibleChapter
Current chapter
​
currentVerse
BibleVerse | null
Current verse or null
​
setVersion
(version: BibleVersion) => void
Update current version
​
setBook
(book: BibleBook) => void
Update current book
​
setChapter
(chapter: BibleChapter) => void
Update current chapter
​
setVerse
(verse: BibleVerse | null) => void
Update current verse

​
Accessing Context

Use the useReaderContext hook to access the reader state: 
import { useReaderContext } from '@youversion/platform-react-hooks';

function CurrentReference() {
  const { currentBook, currentChapter, currentVersion } = useReaderContext();
  
  return (
    <div>
      {currentVersion.abbreviation} {currentBook.human_reference} {currentChapter.number}
    </div>
  );
}

​
VerseSelectionProvider

Manages multi-verse selection state for highlighting or copying multiple verses.

​
Props

​
children
ReactNode
required
Child components

​
Usage

import { VerseSelectionProvider } from '@youversion/platform-react-hooks';

function ChapterWithSelection() {
  return (
    <VerseSelectionProvider>
      <ChapterContent />
      <VerseActions />
    </VerseSelectionProvider>
  );
}

​
Context Value

​
selectedVerseUsfms
Set<string>
Set of selected verse USFM identifiers
​
toggleVerse
(usfm: string) => void
Toggle verse selection state
​
isSelected
(usfm: string) => boolean
Check if a verse is selected
​
clearSelection
() => void
Clear all selected verses
​
selectedCount
number
Number of currently selected verses

​
Accessing Context

Use the useVerseSelection hook: 
import { useVerseSelection } from '@youversion/platform-react-hooks';

function VerseComponent({ usfm }) {
  const { isSelected, toggleVerse } = useVerseSelection();
  
  return (
    <div 
      onClick={() => toggleVerse(usfm)}
      className={isSelected(usfm) ? 'selected' : ''}
    >
      Verse content
    </div>
  );
}

function SelectionActions() {
  const { selectedCount, clearSelection } = useVerseSelection();
  
  if (selectedCount === 0) return null;
  
  return (
    <div>
      {selectedCount} verse(s) selected
      <button onClick={clearSelection}>Clear</button>
    </div>
  );
}

​
YouVersionAuthProvider

This provider is automatically included when you set includeAuth={true} on YouVersionProvider. You should not use it directly.
Manages authentication state including user info, tokens, and OAuth callback processing. Lazy-loaded only when authentication is enabled.

​
Features

  • Automatically handles OAuth callback processing
  • Manages token refresh
  • Caches user information
  • Syncs with YouVersionPlatformConfiguration

​
How It Works

  1. When YouVersionProvider has includeAuth={true}, it lazy-loads YouVersionAuthProvider
  2. The auth provider checks for existing refresh tokens on mount
  3. If on OAuth callback page, processes the callback and caches user info
  4. Provides auth state and user info to useYVAuth hook

​
Props (Internal)

​
config
AuthConfig
required
Configuration object with appKey, apiHost, and redirectUri
​
children
ReactNode
required
Child components

​
Provider Nesting

Providers can be nested to combine functionality: 
import { 
  YouVersionProvider, 
  ReaderProvider,
  VerseSelectionProvider 
} from '@youversion/platform-react-hooks';

function App() {
  return (
    <YouVersionProvider appKey="your-key" includeAuth>
      <ReaderProvider 
        currentVersion={version}
        currentBook={book}
        currentChapter={chapter}
        currentVerse={null}
      >
        <VerseSelectionProvider>
          <BibleReader />
        </VerseSelectionProvider>
      </ReaderProvider>
    </YouVersionProvider>
  );
}

​
Best Practices

YouVersionProvider should wrap your entire application at the root level:
// ✅ Good - at root level
<YouVersionProvider appKey="key">
  <App />
</YouVersionProvider>

// ❌ Bad - nested too deep
<App>
  <SomeComponent>
    <YouVersionProvider appKey="key">
      <Reader />
    </YouVersionProvider>
  </SomeComponent>
</App>
If you have multiple readers on the same page, use separate ReaderProvider instances:
<YouVersionProvider appKey="key">
  <div className="readers">
    <ReaderProvider currentVersion={v1} currentBook={b1} currentChapter={c1} currentVerse={null}>
      <Reader />
    </ReaderProvider>
    
    <ReaderProvider currentVersion={v2} currentBook={b2} currentChapter={c2} currentVerse={null}>
      <Reader />
    </ReaderProvider>
  </div>
</YouVersionProvider>
Place VerseSelectionProvider around the components that need selection state:
// ✅ Good - scoped to chapter view
<ChapterView>
  <VerseSelectionProvider>
    <VerseList />
    <SelectionToolbar />
  </VerseSelectionProvider>
</ChapterView>

// ❌ Unnecessary - too broad if only one component uses it
<VerseSelectionProvider>
  <App />
</VerseSelectionProvider>

Build docs developers (and LLMs) love

Get started for freeTalk to us