Skip to main content
The BibleVersionPicker is a compound component that provides a rich interface for selecting Bible versions with language filtering, search functionality, and recently used versions.

​
Basic Usage

import { useState } from 'react';
import { BibleVersionPicker } from '@youversion/platform-react-ui';

function MyComponent() {
  const [versionId, setVersionId] = useState(111);

  return (
    <BibleVersionPicker.Root
      versionId={versionId}
      onVersionChange={setVersionId}
    >
      <BibleVersionPicker.Trigger />
      <BibleVersionPicker.Content />
    </BibleVersionPicker.Root>
  );
}

​
Component Structure

BibleVersionPicker is a compound component with three parts:
  • BibleVersionPicker.Root - Container that manages state
  • BibleVersionPicker.Trigger - Button to open the picker
  • BibleVersionPicker.Content - The picker dialog content

​
Root Props

​
versionId
number
required
Currently selected version ID.
​
onVersionChange
(versionId: number) => void
Callback when version is selected.
​
background
'light' | 'dark'
Theme override.Default: Inherits from provider
​
side
'top' | 'right' | 'bottom' | 'left'
Position of the popover relative to the trigger.Default: "top"

​
Trigger Props

​
asChild
boolean
Whether to use the child element as the trigger.Default: true
​
children
ReactNode | ((props) => ReactNode)
Custom trigger content or render function. The render function receives:
  • version: Current version object
  • loading: Loading state
Default: Button showing version abbreviation

​
Examples

​
Default Trigger

<BibleVersionPicker.Root versionId={111} onVersionChange={setVersionId}>
  <BibleVersionPicker.Trigger />
  <BibleVersionPicker.Content />
</BibleVersionPicker.Root>

​
Custom Trigger

import { Button } from './ui/button';
import { BookOpenIcon } from './icons/book-open';

<BibleVersionPicker.Root versionId={111} onVersionChange={setVersionId}>
  <BibleVersionPicker.Trigger>
    <Button size="icon">
      <BookOpenIcon className="w-4 h-4" />
    </Button>
  </BibleVersionPicker.Trigger>
  <BibleVersionPicker.Content />
</BibleVersionPicker.Root>

​
Render Function

<BibleVersionPicker.Root versionId={111} onVersionChange={setVersionId}>
  <BibleVersionPicker.Trigger>
    {({ version, loading }) => (
      <button disabled={loading}>
        {loading ? 'Loading...' : version?.title || 'Select version'}
      </button>
    )}
  </BibleVersionPicker.Trigger>
  <BibleVersionPicker.Content />
</BibleVersionPicker.Root>

​
Dark Theme

<BibleVersionPicker.Root
  versionId={111}
  onVersionChange={setVersionId}
  background="dark"
>
  <BibleVersionPicker.Trigger />
  <BibleVersionPicker.Content />
</BibleVersionPicker.Root>

​
Custom Position

<BibleVersionPicker.Root
  versionId={111}
  onVersionChange={setVersionId}
  side="bottom"
>
  <BibleVersionPicker.Trigger />
  <BibleVersionPicker.Content />
</BibleVersionPicker.Root>

​
Features

​
Language Filtering

  • Suggested tab shows regional and browser-preferred languages
  • All tab shows alphabetically sorted languages
  • Language count badge shows available versions
  • Displays language names in English and native script
  • Real-time search across version titles and abbreviations
  • Filters both recent and all versions
  • Search resets when dialog closes or version is selected

​
Recent Versions

  • Automatically tracks last 3 selected versions
  • Stored in localStorage: youversion-platform:picker:recent-versions
  • Recent versions shown at top when present
  • Filtered by search query

​
Version Abbreviation Icons

  • Auto-scaling abbreviation display
  • Splits version codes (e.g., “KJV2” → “KJV” + “2”)
  • Responsive font sizing to fit container

​
Accessibility

  • Keyboard navigation
  • ARIA labels and roles
  • Focus management
  • Screen reader support

​
Persistence

Recent versions are stored in localStorage: 
interface RecentVersion {
  id: number;
  title: string;
  localized_abbreviation: string;
  abbreviation: string;
}

const key = 'youversion-platform:picker:recent-versions';
The picker automatically:
  • Loads recent versions on mount
  • Saves selected versions
  • Maintains max of 3 recent versions
  • Moves selected version to top of list

​
Styling

The picker displays:
  • Version icons with auto-scaled abbreviations
  • Selected version with yv:bg-muted background
  • Language tabs with version count
  • Searchable version list
  • Loading states during API calls

Build docs developers (and LLMs) love

Get started for freeTalk to us