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).
npm install @laravel/passkeysimport { Passkeys } from "@laravel/passkeys";
// Register a new passkey (authenticated user)
await Passkeys.register({ name: "MacBook Pro" });
// Verify passkey
await Passkeys.verify();
// Verify and persist the login
await Passkeys.verify({ remember: true });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>
);
}<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>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}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.
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.
| Method | Description |
|---|---|
configure(options) |
Configure the passkeys client |
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({ remember?, routes? }) |
Verify a passkey |
autofill({ remember?, routes? }) |
Enable passkey autofill on the current page |
cancel() |
Cancel any pending passkey operation |
Use configure() to adjust the fetch options used for passkey requests:
Passkeys.configure({
fetch: {
credentials: "include",
headers: {
"X-Tenant": tenantId,
},
},
});This package handles communication with your Laravel application and expects the following endpoints:
| Method | Route | Purpose |
|---|---|---|
GET |
/passkeys/login/options |
Fetch authentication options |
POST |
/passkeys/login |
Verify credential and authenticate |
| Method | Route | Purpose |
|---|---|---|
GET |
/user/passkeys/options |
Fetch registration options |
POST |
/user/passkeys |
Store new passkey |
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 support route overrides:
type RouteOverrides = {
routes?: {
options?: string;
submit?: string;
};
};Pass remember: true when verifying to keep the user logged in. The flag is
always sent with the login request and defaults to false:
await Passkeys.verify({ remember: true });remember can also be a function. It is called when the login request is
sent, after the passkey ceremony completes, so it can read the current state
of a "Remember me" checkbox. This matters for autofill because the ceremony
starts on page load before the user picks a credential.
await Passkeys.autofill({
remember: () => document.querySelector("#remember").checked,
});The framework adapters accept remember too, and apply it to both verify and
autofill:
// React: a value or a getter
const [rememberMe, setRememberMe] = useState(false);
usePasskeyVerify({ autofill: true, remember: rememberMe });// Vue: a value, a ref, or a getter
const rememberMe = ref(false);
usePasskeyVerify({ autofill: true, remember: rememberMe });// Svelte: pass a getter so $state stays live
let rememberMe = $state(false);
usePasskeyVerify({ autofill: true, remember: () => rememberMe });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();
},
});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 |
InvalidDomainError |
Passkeys are used from an invalid domain |
ServerError |
The server answered with an error status, kept in status |
UnexpectedResponseError |
The server returned something other than JSON, such as a redirect from a guest-only route when the user is already signed in. Has url and redirected properties |
PasskeyError |
Base class; used for any unmapped failures |
Every other error keeps the error it was converted from as cause. A TypeError cause usually means fetch failed and the request never reached the server, and the cause of a UserCancelledError tells a dismissed prompt apart from one that timed out:
import { ServerError } from "@laravel/passkeys";
if (error instanceof ServerError && error.status === 419) {
// The page's CSRF token has expired, so ask the user to reload it.
} else if (error.cause instanceof TypeError) {
// The request most likely never reached the server, so ask the user to check their connection.
}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;
}If a user who is already signed in tries to log in again, for example from a second tab, Laravel redirects the guest-only login routes. Send them to the redirect target:
import { Passkeys, UnexpectedResponseError } from "@laravel/passkeys";
try {
await Passkeys.verify();
} catch (error) {
if (error instanceof UnexpectedResponseError && error.redirected) {
window.location.href = error.url;
}
}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.
| Entry Point | Exports |
|---|---|
@laravel/passkeys |
Passkeys |
@laravel/passkeys/react |
usePasskeyVerify, usePasskeyRegister |
@laravel/passkeys/vue |
usePasskeyVerify, usePasskeyRegister |
@laravel/passkeys/svelte |
usePasskeyVerify, usePasskeyRegister |