use-web-authn

Encode bytes as unpadded base64url.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useWebAuthn, encodeBase64Url, decodeBase64Url, parseCreationOptionsFromJSON, parseRequestOptionsFromJSON, serializeRegistrationCredential, serializeAuthenticationCredential } from "@vizejs/composable/use-web-authn";

Try it

Offer passkey sign-in

Check for a built-in authenticator before offering to create a passkey.

Open the interactive example

What to observe: Check for passkey support reports whether this device can create a passkey.

create and get accept JSON options from your server and return JSON-ready credentials. Every example renders a neutral message until it mounts, so server and client markup match, and then explains what to do when the browser lacks the API.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { ref } from "vue";
import { useMounted } from "@vizejs/composable/use-mounted";
import { useWebAuthn } from "@vizejs/composable/use-web-authn";

const mounted = useMounted();
const { supported, isUserVerifyingPlatformAuthenticatorAvailable } = useWebAuthn();
const platform = ref<boolean>();

async function check() {
  platform.value = await isUserVerifyingPlatformAuthenticatorAvailable();
}
</script>

<template>
  <div class="composable-example">
    <p>Offer passkey sign-in only on devices with a built-in authenticator.</p>
    <button type="button" :disabled="!mounted || !supported" @click="check">
      Check for passkey support
    </button>
    <output aria-live="polite">{{
      !mounted
        ? "Checking browser support…"
        : !supported
          ? "WebAuthn is not available in this browser."
          : platform === undefined
            ? "WebAuthn is available."
            : platform
              ? "This device can create a passkey."
              : "No built-in authenticator; offer a security key or password."
    }}</output>
  </div>
</template>

Runtime contract

API

encodeBase64Url

Encode bytes as unpadded base64url.

function encodeBase64Url(bytes: ArrayBuffer | ArrayBufferView): string

decodeBase64Url

Decode base64url (padded or unpadded) into bytes.

function decodeBase64Url(text: string): Uint8Array<ArrayBuffer>

parseCreationOptionsFromJSON

Convert server creation-options JSON into binary options for create.

function parseCreationOptionsFromJSON( json: PublicKeyCredentialCreationOptionsJSON, ): WebAuthnCreationInit

parseRequestOptionsFromJSON

Convert server request-options JSON into binary options for get.

function parseRequestOptionsFromJSON( json: PublicKeyCredentialRequestOptionsJSON, ): WebAuthnRequestInit

serializeRegistrationCredential

Serialize a registration credential into JSON-safe base64url fields.

function serializeRegistrationCredential( credential: RegistrationCredentialLike, ): RegistrationResponseJSON

serializeAuthenticationCredential

Serialize an authentication credential into JSON-safe base64url fields.

function serializeAuthenticationCredential( credential: AuthenticationCredentialLike, ): AuthenticationResponseJSON

useWebAuthn

Register and authenticate passkeys with the Web Authentication API. create and get accept binary options or server JSON, run one ceremony at a time (starting one aborts the previous), and resolve to a discriminated WebAuthnResult. Use the exported pure helpers to serialize results for the server. A pending ceremony is aborted when the owning reactive scope stops; outside a scope call abort(). Server rendering: nothing is requested, supported and pending are false.

function useWebAuthn(options: UseWebAuthnOptions = {}): WebAuthnControls

const webAuthn = useWebAuthn();
const result = await webAuthn.get(await fetchJSON("/login/options"));
if (result.status === "success") await post(serializeAuthenticationCredential(result.credential));

Types

PublicKeyCredentialDescriptorJSON

Credential descriptor in server JSON form.

WebAuthnCredentialDescriptor

Credential descriptor in binary form.

WebAuthnAuthenticatorSelection

Authenticator selection criteria of a registration ceremony.

WebAuthnRelyingParty

Relying party entity.

WebAuthnCredentialParameter

Public-key algorithm parameter.

PublicKeyCredentialCreationOptionsJSON

PublicKeyCredentialCreationOptions as serialized by a server (binary fields base64url).

PublicKeyCredentialRequestOptionsJSON

PublicKeyCredentialRequestOptions as serialized by a server (binary fields base64url).

WebAuthnCreationInit

Binary creation options passed to navigator.credentials.create.

WebAuthnRequestInit

Binary request options passed to navigator.credentials.get.

PublicKeyCredentialLike

Fields shared by every returned PublicKeyCredential.

RegistrationCredentialLike

Credential returned by a registration ceremony.

AuthenticationCredentialLike

Credential returned by an authentication ceremony.

RegistrationResponseJSON

JSON-safe registration result, ready to POST to a server.

AuthenticationResponseJSON

JSON-safe authentication result, ready to POST to a server.

WebAuthnCredentialsHost

Minimal navigator.credentials consumed by useWebAuthn.

PublicKeyCredentialStatics

Static capability checks of PublicKeyCredential.

UseWebAuthnOptions

Options for useWebAuthn.

WebAuthnCeremonyOptions

Per-ceremony options of WebAuthnControls.create and WebAuthnControls.get.

WebAuthnControls

Reactive state and actions returned by useWebAuthn.