Swift SDK

Components

Copy page

The Swift SDK provides SwiftUI components and API helpers for integrating Bible content into iOS and iPadOS applications. Complete the Quick Start before using these examples.

Display Content with BibleCardView

BibleCardView is the fastest and easiest way to display a Bible passage. Provide a BibleReference describing the version, book, and verse range you want to display, and optionally adjust the font size.

Code
import SwiftUI
import YouVersionPlatform

struct ExampleView: View {
    var body: some View {
        BibleCardView(
            reference: BibleReference(
                versionId: 3034, bookUSFM: "2CO", chapter: 1, verseStart: 3, verseEnd: 4
            ),
            fontSize: 18
        )
    }
}

#Preview {
    ExampleView()
}

BibleCardView will fetch and format the passage automatically, including displaying copyright information.

Let users switch versions with the version picker

Pass showVersionPicker: true to render a version-picking button in the card's header. Tapping it opens a sheet where the user can pick a different Bible version, and the card re-renders the passage in the selected version automatically.

Code
BibleCardView(
    reference: BibleReference(
        versionId: 3034, bookUSFM: "2CO", chapter: 1, verseStart: 3, verseEnd: 4
    ),
    fontSize: 18,
    showVersionPicker: true
)

Provide an optional onVersionChange closure if you want to react to the user's selection — for example, to persist their preferred version so it can be used as the default the next time the card is shown.

Code
BibleCardView(
    reference: BibleReference(
        versionId: 3034, bookUSFM: "JHN", chapter: 3, verseStart: 16, verseEnd: 16
    ),
    showVersionPicker: true,
    onVersionChange: { version in
        // Persist version.id, refresh other UI, etc.
    }
)

By default, the version picker offers Bible versions in every available language. To limit the picker to specific languages, pass permittedLanguageTags during configuration.

Code
YouVersionPlatformConfiguration.configure(
    appKey: "YOUR_APP_KEY_HERE",
    permittedLanguageTags: ["en"]
)

Language tags follow BCP 47, such as "en" for English or "es" for Spanish. When the filtered list only contains versions in one language, the language button in the version picker is hidden automatically.

You can also limit the picker to specific Bible versions with permittedVersionIds:

Code
YouVersionPlatformConfiguration.configure(
    appKey: "YOUR_APP_KEY_HERE",
    permittedVersionIds: [111, 3034]
)

Version IDs are YouVersion Bible version IDs. permittedVersionIds can be combined with permittedLanguageTags by providing both parameters in the call to .configure(); in that case a Bible version would need to match both filters to be shown.

To exclude specific Bible versions while leaving every other available version selectable, pass excludedVersionIds:

Code
YouVersionPlatformConfiguration.configure(
    appKey: "YOUR_APP_KEY",
    excludedVersionIds: [123, 456]
)

Display Content with BibleTextView

Use BibleTextView when you want inline scripture rendering in your own layouts. Unlike BibleCardView this is "merely" the nicely formatted text of the Bible passage: it doesn't include elements to show the verse reference, doesn't show the Bible version's name or its copyright information - you need to provide those separately. See Copyright & Attribution for a complete example that keeps the passage and its version metadata in sync. You can pass a single verse, a verse range, or a full chapter reference.

Single verse

Code
import SwiftUI
import YouVersionPlatform

struct SingleVerseView: View {
    var body: some View {
        BibleTextView(
            BibleReference(versionId: 3034, bookUSFM: "JHN", chapter: 3, verse: 16)
        )
    }
}

Verse range

Code
import SwiftUI
import YouVersionPlatform

struct VerseRangeView: View {
    var body: some View {
        BibleTextView(
            BibleReference(versionId: 3034, bookUSFM: "JHN", chapter: 3, verseStart: 16, verseEnd: 20)
        )
    }
}

Full chapter

Code
import SwiftUI
import YouVersionPlatform

struct ChapterView: View {
    var body: some View {
        BibleTextView(
            BibleReference(versionId: 3034, bookUSFM: "JHN", chapter: 3)
        )
    }
}

For longer passages, wrap BibleTextView in a ScrollView.

Embed a Full Reader with BibleReaderView

BibleReaderView provides a complete Bible reading experience that can be embedded in your app.

Code
import SwiftUI
import YouVersionPlatform

struct ReaderTabView: View {
    var body: some View {
        BibleReaderView()
    }
}

To open the reader to a specific passage, pass a BibleReference:

Code
BibleReaderView(
    reference: BibleReference(versionId: 3034, bookUSFM: "PSA", chapter: 23)
)

Navigate the reader from elsewhere in your app

Use a shared BibleReaderNavigation object to move the reader to a new passage from another screen, such as a Read button in a different tab. Call request(_:showsFullChapter:) with the passage, then use your app's navigation to bring the reader on screen. The existing reader moves to the requested passage without being recreated.

Code
@State private var readerNavigation = BibleReaderNavigation()
@State private var selectedTab = Tab.home

var body: some View {
    TabView(selection: $selectedTab) {
        HomeView(onReadTap: { reference in
            readerNavigation.request(reference, showsFullChapter: true)
            selectedTab = .bible
        })
        .tabItem { Label("Home", systemImage: "house") }
        .tag(Tab.home)

        BibleReaderView.restoringLastPassage(
            readerNavigation: readerNavigation
        )
        .tabItem { Label("Bible", systemImage: "book.closed") }
        .tag(Tab.bible)
    }
}

The reader can receive a pending request even when it is not currently on screen. Your app remains responsible for switching tabs, presenting a sheet, or pushing the reader onto a navigation stack.

On iOS 18 and later, call focusReference(_:) to display the verse in its full chapter and dim the surrounding verses:

Code
if #available(iOS 18.0, *) {
    readerNavigation.focusReference(reference)
}

The focus clears when the user scrolls, taps a verse, or navigates to another passage.

Disabling Sign-In

By default, tapping a highlight color on an unauthenticated verse selection prompts the user to sign in with YouVersion. To suppress SDK-provided sign-in UI, configure the SDK with isSignInEnabled: false:

Code
YouVersionPlatformConfiguration.configure(
    appKey: "YOUR_APP_KEY_HERE",
    isSignInEnabled: false
)

When sign-in is disabled, the SDK suppresses UI such as the highlight sign-in prompt, the header menu sign-in option, and the version-download auth check. Highlight controls are hidden from the verse actions drawer; copy and share remain available.

Built-in Sign-In via BibleReaderView

When isSignInEnabled is true, BibleReaderView handles built-in sign-in automatically using the globally configured appName and signInPromptMessage.

Code
YouVersionPlatformConfiguration.configure(
    appKey: "YOUR_APP_KEY_HERE",
    appName: "Your App Name",
    signInPromptMessage: "Sign in to see your YouVersion highlights."
)

Implement Sign In

If your app needs authenticated user data or a custom sign-in flow outside the BibleReaderView, you can use SignInWithYouVersionButton, SignInWithYouVersionView, or call YouVersionAPI.Users.signIn(...) directly.

SignInWithYouVersionButton

Add the sign-in button and pass a presentation context.

Code
import AuthenticationServices
import SwiftUI
import UIKit
import YouVersionPlatform

class ContextProvider: NSObject, ASWebAuthenticationPresentationContextProviding {
    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
        guard let scene = UIApplication.shared.connectedScenes.first as? UIWindowScene,
              let window = scene.windows.first else {
            return ASPresentationAnchor()
        }
        return window
    }
}

struct SignInView: View {
    @State private var contextProvider = ContextProvider()

    var body: some View {
        SignInWithYouVersionButton {
            Task {
                do {
                    let result = try await YouVersionAPI.Users.signIn(
                        permissions: [.profile, .email],
                        contextProvider: contextProvider
                    )
                    // Use result.accessToken for authenticated API calls.
                } catch {
                    print(error)
                }
            }
        }
    }
}

SignInWithYouVersionView

The SDK also exposes a reusable sign-in prompt view that you can present in your own sheet or navigation flow.

Code
SignInWithYouVersionView(
    onSignIn: { /* trigger your sign-in logic */ },
    onDismiss: { /* dismiss the sheet */ }
)

SignInWithYouVersionView reads appName and signInPromptMessage from YouVersionPlatformConfiguration and accepts optional colors for theming.

The SDK stores the access token locally and persists it across app launches.

Display Verse of the Day

Use VotdView to quickly render the Verse of the Day:

Code
import SwiftUI
import YouVersionPlatform

struct VotdCardView: View {
    var body: some View {
        VotdView()
    }
}

Or fetch Verse of the Day data and render it with your own UI:

Code
let dayOfYear = Calendar.current.ordinality(of: .day, in: .year, for: Date())!
let votd = try await YouVersionAPI.VOTD.verseOfTheDay(dayOfYear: dayOfYear)
// Use votd.reference with BibleTextView or BibleCardView.

Example code

See the SampleApp project in the Examples folder to see the above code in action!