Skip to content
VprogrammersPublic

About

Accessible OTP input for Compose Multiplatform, targeting Android and iOS. Customizable styling, single-field editing, paste support, and platform autofill integration.

Resources

Contributing

Accessibility

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

a11y-otp

An accessibility-first one-time code field for Android and iOS. One real text field, drawn as boxes. Native on each platform: Jetpack Compose on Android and UIKit on iOS. Add it once to your Kotlin Multiplatform shared module; no Swift package needed.

Kotlin Platforms License

Status: 0.3.0. While the version is 0.x, minor versions may still change the API; every change is listed in the changelog. Behavior is claimed as supported only after it is verified (see Accessibility).

Why

Most OTP components render one text field per digit. It looks right, but it breaks the things that matter:

One field per digit a11y-otp (one field)
Screen reader "Text field, text field, text field…" six times One field with a label, progress and the entered code
SMS autofill Often fills only the first box Fills the whole code
Paste Breaks or lands in one box Works, including 482-913 and 482 913
Backspace Fragile focus jumping Native behavior

The boxes are decoration. Underneath is a single platform text input, so TalkBack, VoiceOver, autofill and paste treat it as one ordinary field.

What you get

  • OtpField: the code input, with a label, progress, an error state and a rejection message for codes of the wrong length.
  • OtpVerifyButton and OtpResendButton (with a countdown you drive).
  • OtpState: an immutable state you own, shared by both platforms.
  • An optional Android module, a11yotp-sms-retriever, that fills the code from an SMS without permissions.

Your app owns the state, the server verification, the resend timer and all text (so everything can be localized). The library never makes network calls and never asks for SMS permissions.

Requirements

Minimum
Kotlin 2.4.21 (Kotlin/Native libraries need a compiler at least as new as the one that built them)
Android minSdk 24, compileSdk 37, Jetpack Compose
iOS 18.2, arm64 device and arm64 simulator; UIKit components, embeddable in SwiftUI

Installation

Add the library to your KMP shared module only. The Android app gets the Compose components through it, and the iOS app gets the UIKit components through the shared framework.

// shared/build.gradle.kts
kotlin {
    listOf(iosArm64(), iosSimulatorArm64()).forEach {
        it.binaries.framework {
            baseName = "Shared"
            export("me.vprogrammers:a11yotp:0.3.0") // makes the iOS components visible to Swift
        }
    }
    sourceSets.commonMain.dependencies {
        api("me.vprogrammers:a11yotp:0.3.0") // api, so androidApp sees the Compose components
    }
}

The artifacts are on Maven Central (mavenCentral()):

Artifact Contents
me.vprogrammers:a11yotp OtpState and the Android and iOS components
me.vprogrammers:a11yotp-sms-retriever optional, Android only: SMS Retriever and SMS User Consent

Quick start

Android (Compose):

var otp by rememberSaveable(stateSaver = OtpStateSaver) { mutableStateOf(OtpState(OtpLength.SIX)) }

OtpField(
    state = otp,
    onStateChange = { otp = it },
    onComplete = { code -> viewModel.verify(code) },
    accessibility = OtpFieldAccessibility(
        label = "Verification code",
        errorMessage = "Incorrect code. Try again.",
        progressDescription = { "${it.entered} of ${it.total} digits entered" },
        inputRejectedMessage = { "Code not entered: it has ${it.receivedDigitCount} digits, but ${it.expectedDigitCount} are expected." },
    ),
)

iOS (Swift):

import Shared

let field = OtpField(
    state: OtpState(length: .six),
    accessibility: OtpFieldAccessibility(
        label: "Verification code",
        errorMessage: "Incorrect code. Try again.",
        progressDescription: { "\($0.entered) of \($0.total) digits entered" },
        inputRejectedMessage: { "Code not entered: it has \($0.receivedDigitCount) digits, but \($0.expectedDigitCount) are expected." }
    ),
    doneButtonTitle: "Done"
)
field.onStateChange = { [weak field] newState in field?.state = newState }
field.onComplete = { code in verify(code) }
// Add field.view to your view hierarchy and keep `field` alive while it is on screen.

When verification fails, set otp = otp.withError() (Android) or field.state = field.state.withError() (iOS). The field shows and announces errorMessage.

Documentation

Document Read it for
API reference Every public type and function, for shared code, Android and iOS (Dokka)
Getting started The complete integration on both platforms, SwiftUI, the buttons, the error flow
Input rules What the field accepts: typing, paste, autofill, normalization, lengths, rejection, completion
Customization Styles, colors, dark mode, masks, alignment, grouping, the iOS Done key
Accessibility What screen readers announce, WCAG coverage, what is verified, a checklist for your app
The OTP message How to write the SMS so iOS and Android offer the code, for numeric and alphanumeric codes
SMS Retriever Optional automatic SMS delivery on Android, the app hash and the message format
SMS User Consent Optional on Android: fill the code from any SMS after the user allows a system prompt
Contributing Building, local checks, CI, the public API baseline, releasing
Changelog Changes per version

The androidApp and iosApp sample apps (with sample/shared as their shared module) show every option, and iosApp/iosApp/Components/ has ready-to-copy SwiftUI wrappers.

What this library does not do

  • No network calls or code verification
  • No resend timer: the resend button shows the seconds you pass in
  • No SMS reading in the core library and no SMS permissions
  • No rate limiting: your server must limit attempts
  • Codes of 4, 6 or 8 characters: digits, or digits and the letters A–Z (autofill suggestions for codes with letters depend on the platform and keyboard)

Roadmap

  • Shared OTP state and normalization
  • Android Compose component
  • iOS UIKit component (Kotlin/Native)
  • Masked mode
  • Optional SMS Retriever module for Android
  • Real-device verification with TalkBack and VoiceOver
  • Maven Central publication (0.1.0, 0.2.0, 0.3.0)
  • Real-device verification with Voice Control, Switch Access, Switch Control, hardware keyboards, RTL and iPad
  • Alphanumeric codes
  • Optional Compose Multiplatform UI module
  • Optional SMS User Consent support for Android

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md. For accessibility bugs, please include the platform and OS version, the assistive technology and its version, and what was announced compared with what you expected.

License

MIT. See LICENSE.

About

Accessible OTP input for Compose Multiplatform, targeting Android and iOS. Customizable styling, single-field editing, paste support, and platform autofill integration.

Resources

Contributing

Accessibility

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages