@laravel/passkeys

A JavaScript client for passkey authentication designed to work with Laravel applications. It provides a fluent API for browser-side WebAuthn ceremonies (registration and authentication).

Installation

npm install @laravel/passkeys

Quick Start

import { Passkeys } from "@laravel/passkeys";

// Register a new passkey (authenticated user)
await Passkeys.register({ name: "MacBook Pro" });

// Verify passkey
await Passkeys.verify();

Framework Helpers

React

import { useState } from "react";
import { usePasskeyVerify, usePasskeyRegister } from "@laravel/passkeys/react";

// Login
function LoginPage() {
    const { verify, isLoading, error, isSupported } = usePasskeyVerify({
        autofill: true,
        onSuccess: (response) => {
            if (response.redirect) {
                window.location.href = response.redirect;
            }
        },
    });

    return (
        <div>
            {/* Add webauthn and set autofill: true to show passkeys in the input */}
            <input type="text" autoComplete="email webauthn" />

            <button onClick={verify} disabled={!isSupported || isLoading}>
                {isLoading ? "Authenticating..." : "Sign in with passkey"}
            </button>
            {error && <p className="error">{error}</p>}
        </div>
    );
}

// Register
function RegisterForm() {
    const [name, setName] = useState("");
    const { register, isLoading, error } = usePasskeyRegister();

    return (
        <div>
            <input
                value={name}
                onChange={(e) => setName(e.target.value)}
                placeholder="Passkey name"
            />
            <button
                onClick={() => register(name)}
                disabled={isLoading || !name}
            >
                {isLoading ? "Registering..." : "Add passkey"}
            </button>
            {error && <p className="error">{error}</p>}
        </div>
    );
}

Vue

<script setup>
import { ref } from "vue";
import { usePasskeyVerify, usePasskeyRegister } from "@laravel/passkeys/vue";
import { router } from "@inertiajs/vue3";

// Login
const {
    verify,
    isLoading: verifyLoading,
    error: verifyError,
} = usePasskeyVerify({
    autofill: true,
    onSuccess: (response) => {
        if (response.redirect) {
            router.visit(response.redirect);
        }
    },
});

// Register
const name = ref("");
const {
    register,
    isLoading: registerLoading,
    error: registerError,
} = usePasskeyRegister();
</script>

<template>
    <!-- Include webauthn and set autofill: true to show passkeys in the input -->
    <input type="text" autocomplete="email webauthn" />

    <button @click="verify" :disabled="verifyLoading">
        {{ verifyLoading ? "Authenticating..." : "Sign in with passkey" }}
    </button>
    <p v-if="verifyError" class="error">{{ verifyError }}</p>

    <!-- Register -->
    <input v-model="name" placeholder="Passkey name" />
    <button @click="register(name)" :disabled="registerLoading || !name">
        {{ registerLoading ? "Registering..." : "Add passkey" }}
    </button>
    <p v-if="registerError" class="error">{{ registerError }}</p>
</template>

Svelte

Access the returned values through the hook object (don't destructure), so Svelte's reactivity stays live:

<script>
    import { usePasskeyVerify, usePasskeyRegister } from "@laravel/passkeys/svelte";

    const verify = usePasskeyVerify({
        autofill: true,
        onSuccess: (response) => {
            if (response.redirect) window.location.href = response.redirect;
        },
    });

    const register = usePasskeyRegister();
    let name = $state("");
</script>

<!-- Include webauthn and set autofill: true to show passkeys in the input -->
<input type="email" autocomplete="email webauthn" />

<button onclick={verify.verify} disabled={!verify.isSupported || verify.isLoading}>
    {verify.isLoading ? "Authenticating..." : "Sign in with passkey"}
</button>
{#if verify.error}<p class="error">{verify.error}</p>{/if}

<input bind:value={name} placeholder="Passkey name" />
<button
    onclick={() => register.register(name)}
    disabled={register.isLoading || !name}
>
    {register.isLoading ? "Registering..." : "Add passkey"}
</button>
{#if register.error}<p class="error">{register.error}</p>{/if}

Server-Side Rendering

WebAuthn is a browser-only API. The framework hooks are SSR-safe: on the server and during hydration, isSupported renders as false, then updates to the real value after the component mounts. This avoids hydration warnings without any user-visible flash — in Vue and Svelte the post-mount update runs as a microtask before the browser paints; in React it's handled by useSyncExternalStore (client-only apps see the real value on the first render).

If you need the synchronous value outside a component lifecycle, call Passkeys.isSupported() directly — it returns false under Node without throwing.

Passkey Autofill

When autofill: true is passed, the hook asks the browser to surface saved passkeys inside the native credential-picker dropdown. The browser attaches that dropdown to an <input> whose autocomplete attribute includes the webauthn token (typically alongside username or email). If no such input is mounted by the time the autofill request starts, the dropdown has nowhere to anchor and silently shows nothing — no error, no console warning, just no picker.

If the browser doesn't support autofill (checked via isAutofillSupported()) or the user dismisses the picker, the hook falls back to doing nothing and your explicit "Sign in with passkey" button still works.

Core API

Public Methods

Method	Description
isSupported()	Check if the browser supports passkeys
isAutofillSupported()	Check if the browser supports passkey autofill
register({ name, routes? })	Register a new passkey for the authenticated user
verify(options?)	Verify a passkey
autofill(options?)	Enable passkey autofill on the current page
cancel()	Cancel any pending passkey operation

Expected Endpoints

This package handles communication with your Laravel application and expects the following endpoints:

Authentication (Guest)

Method	Route	Purpose
GET	/passkeys/login/options	Fetch authentication options
POST	/passkeys/login	Verify credential and authenticate

Registration (Authenticated)

Method	Route	Purpose
GET	/user/passkeys/options	Fetch registration options
POST	/user/passkeys	Store new passkey

Per-Call Route Overrides

await Passkeys.register({
    name: "MacBook Pro",
    routes: {
        options: "/user/security/passkeys/options",
        submit: "/user/security/passkeys",
    },
});

await Passkeys.verify({
    routes: {
        options: "/passkeys/confirm/options",
        submit: "/passkeys/confirm",
    },
});

register(), verify(), and autofill() all use:

type RouteOverrides = {
    routes?: {
        options?: string;
        submit?: string;
    };
};

React / Vue / Svelte Route Overrides

The usePasskeyVerify adapters accept:

usePasskeyVerify({
    autofill: true,
    routes: {
        options: "/passkeys/confirm/options",
        submit: "/passkeys/confirm",
    },
    onSuccess: (response) => {
        if (response.redirect) {
            window.location.href = response.redirect;
        }
    },
});

The usePasskeyRegister adapters accept:

usePasskeyRegister({
    routes: {
        options: "/user/security/passkeys/options",
        submit: "/user/security/passkeys",
    },
    onSuccess: () => {
        window.location.reload();
    },
});

Typed Errors

All ceremony failures are converted to PasskeyError subclasses so you can branch on error type:

Class	Thrown when
NotSupportedError	The browser does not support WebAuthn
UserCancelledError	The user dismissed the native prompt
PasskeyExistsError	A passkey for this account/device is already registered
PasskeyError	Base class; used for server errors and any unmapped failures

Passkeys.register() and Passkeys.verify() throw these directly. The framework adapters expose them two ways: the onError callback receives the typed instance, and each hook returns an errorInstance field (alongside the string error) so you can branch from markup:

import { PasskeyExistsError } from "@laravel/passkeys";
import { usePasskeyRegister } from "@laravel/passkeys/react";

const { register, error, errorInstance } = usePasskeyRegister();

// ...
{
    errorInstance instanceof PasskeyExistsError ? (
        <p>You already registered a passkey on this device.</p>
    ) : error ? (
        <p className="error">{error}</p>
    ) : null;
}

Type Compatibility

This package uses TypeScript types from @simplewebauthn/browser. These types are fully compatible with the JSON output from the web-auth/webauthn-lib PHP package.

Package Exports

Entry Point	Exports
@laravel/passkeys	Passkeys
@laravel/passkeys/react	usePasskeyVerify, usePasskeyRegister
@laravel/passkeys/vue	usePasskeyVerify, usePasskeyRegister
@laravel/passkeys/svelte	usePasskeyVerify, usePasskeyRegister