Data hooks provide a consistent interface for fetching and managing data from the YouVersion Platform API. All hooks follow the useApiData pattern and return { data, loading, error, refetch }.
Bible Content Hooks useVersion Fetches metadata for a specific Bible version.
The Bible version ID (e.g., 1 for KJV, 3034 for BSB)
Optional configuration object with enabled boolean
Bible version metadata including title, abbreviation, language, and more
True while data is being fetched
Error object if the request failed
Function to manually refetch the data
Usage import { useVersion } from '@youversion/platform-react-hooks' ; function VersionInfo ({ versionId }) { const { version , loading , error } = useVersion ( versionId ); if ( loading ) return < div > Loading... </ div > ; if ( error ) return < div > Error: { error . message } </ div > ; return ( < div > < h2 > { version ?. title } </ h2 > < p > { version ?. abbreviation } - { version ?. language . name } </ p > </ div > ); }
useVersions Fetches a list of Bible versions, optionally filtered by language and license.
languageRanges
string | string[]
default: "en"
Language code(s) to filter by (e.g., ‘en’, [‘en’, ‘es’])
Optional license ID to filter versions
Configuration object for pagination, field selection, and fetching behavior
Options Maximum results per page, or '' for all (requires 1-3 fields when using ' ')
Specific fields to return (required when page_size is ’*’)
Include all available versions regardless of license
Enable/disable automatic fetching
Returns versions
Collection<BibleVersion> | null
Collection of Bible versions with pagination metadata
Usage Basic
With Pagination
Multiple Languages
import { useVersions } from '@youversion/platform-react-hooks' ; function VersionList () { const { versions , loading } = useVersions ( 'en' ); if ( loading ) return < div > Loading... </ div > ; return ( < ul > { versions ?. data . map ( v => ( < li key = { v . id } > { v . title } </ li > )) } </ ul > ); }
useBook Fetches metadata for a specific book within a Bible version.
USFM book abbreviation (e.g., ‘GEN’, ‘JHN’, ‘PSA’)
Returns Book metadata including chapters, human reference, and intro
Usage import { useBook } from '@youversion/platform-react-hooks' ; function BookInfo ({ versionId , bookId }) { const { book , loading } = useBook ( versionId , bookId ); if ( loading ) return < div > Loading... </ div > ; return ( < div > < h2 > { book ?. human_reference } </ h2 > < p > { book ?. chapters ?. length } chapters </ p > </ div > ); }
useBooks Fetches all books for a specific Bible version.
Returns books
Collection<BibleBook> | null
Collection of all books in the version
Usage import { useBooks } from '@youversion/platform-react-hooks' ; function TableOfContents ({ versionId }) { const { books , loading } = useBooks ( versionId ); if ( loading ) return < div > Loading... </ div > ; return ( < nav > { books ?. data . map ( book => ( < a key = { book . id } href = { `/bible/ ${ book . id } ` } > { book . human_reference } </ a > )) } </ nav > ); }
useChapter Fetches a specific chapter’s content.
Returns Chapter content and metadata
Usage import { useChapter } from '@youversion/platform-react-hooks' ; function ChapterView () { const { chapter , loading , error } = useChapter ( 1 , 'JHN' , 3 ); if ( loading ) return < div > Loading... </ div > ; if ( error ) return < div > Error: { error . message } </ div > ; return < div dangerouslySetInnerHTML = { { __html: chapter ?. content } } /> ; }
useVerse Fetches a specific verse.
Returns Verse content and metadata
Usage import { useVerse } from '@youversion/platform-react-hooks' ; function SingleVerse () { const { verse , loading } = useVerse ( 1 , 'JHN' , 3 , 16 ); if ( loading ) return < div > Loading... </ div > ; return < p > { verse ?. text } </ p > ; }
usePassage Fetches a passage using USFM notation (supports ranges like “JHN.3.16-18”).
USFM passage identifier (e.g., ‘JHN.3.16’, ‘JHN.3.16-18’)
format
'html' | 'text'
default: "html"
Content format
Returns Passage content and metadata
Usage Single Verse
Verse Range
Plain Text
import { usePassage } from '@youversion/platform-react-hooks' ; function PassageView () { const { passage , loading } = usePassage ({ versionId: 1 , usfm: 'JHN.3.16' , }); if ( loading ) return < div > Loading... </ div > ; return < div dangerouslySetInnerHTML = { { __html: passage ?. content } } /> ; }
useVOTD Fetches the Verse of the Day for a specific day of the year.
Day of year (1-366). Use the getDayOfYear utility to calculate from a Date.
Returns Verse of the Day including verse content, reference, and image
Usage Today's Verse
Specific Date
import { useVOTD , getDayOfYear } from '@youversion/platform-react-hooks' ; function DailyVerse () { const today = getDayOfYear ( new Date ()); const { data : votd , loading , refetch } = useVOTD ( today ); if ( loading ) return < div > Loading... </ div > ; return ( < div > < p > { votd ?. verse . text } </ p > < small > { votd ?. verse . reference } </ small > < button onClick = { refetch } > Refresh </ button > </ div > ); }
Language Hooks useLanguages Fetches available languages with optional filtering and pagination.
Query options for filtering and pagination
Hook configuration (enable/disable fetching)
Options Specific fields to return
Returns languages
Collection<Language> | null
Collection of languages with pagination metadata
Usage import { useLanguages } from '@youversion/platform-react-hooks' ; function LanguageSelector () { const { languages , loading } = useLanguages (); if ( loading ) return < div > Loading... </ div > ; return ( < select > { languages ?. data . map ( lang => ( < option key = { lang . id } value = { lang . id } > { lang . name } </ option > )) } </ select > ); }
Highlight Hooks useHighlights Fetches, creates, and deletes user highlights (requires authentication).
Query options for filtering highlights
Options Returns highlights
Collection<Highlight> | null
User’s highlights
createHighlight
(data: CreateHighlight) => Promise<Highlight>
Create a new highlight
deleteHighlight
(passageId: string, options?: DeleteHighlightOptions) => Promise<void>
Delete a highlight
Usage import { useHighlights } from '@youversion/platform-react-hooks' ; function HighlightManager ({ versionId }) { const { highlights , loading , createHighlight , deleteHighlight } = useHighlights ({ version_id: versionId }); const handleCreate = async () => { await createHighlight ({ passage_id: 'JHN.3.16' , version_id: versionId , color: 'yellow' , }); }; const handleDelete = async ( passageId : string ) => { await deleteHighlight ( passageId ); }; if ( loading ) return < div > Loading... </ div > ; return ( < div > < button onClick = { handleCreate } > Highlight Verse </ button > < ul > { highlights ?. data . map ( h => ( < li key = { h . passage_id } > { h . passage_id } < button onClick = { () => handleDelete ( h . passage_id ) } > Delete </ button > </ li > )) } </ ul > </ div > ); }
Client Hooks useBibleClient Returns a configured BibleClient instance. Used internally by data hooks.
Returns Configured Bible API client
Usage import { useBibleClient } from '@youversion/platform-react-hooks' ; function CustomDataFetcher () { const client = useBibleClient (); // Use client for custom API calls const fetchCustomData = async () => { const version = await client . getVersion ( 1 ); // ... }; // ... }
Best Practices
Use conditional fetching to avoid unnecessary requests
// ✅ Good - only fetches when IDs are valid const { chapter } = useChapter ( versionId , book , chapterNum , { enabled: Boolean ( versionId && book && chapterNum ), }); // ❌ Bad - fetches even with invalid params const { chapter } = useChapter ( 0 , '' , 0 );
Handle all states for better UX
const { version , loading , error } = useVersion ( versionId ); if ( loading ) return < Spinner /> ; if ( error ) return < ErrorMessage error = { error } /> ; if ( ! version ) return < NotFound /> ; return < VersionDisplay version = { version } /> ;
Use refetch for user-triggered updates
const { data : votd , loading , refetch } = useVOTD ( dayOfYear ); return ( < div > < Verse verse = { votd ?. verse } /> < button onClick = { refetch } disabled = { loading } > { loading ? 'Refreshing...' : 'Refresh' } </ button > </ div > );
