Getting Started

Install

bun add @capgo/capacitor-nfc
bunx cap sync

Import

import { CapacitorNfc } from '@capgo/capacitor-nfc';

API Overview

startScanning

Starts listening for NFC tags.

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.startScanning();

stopScanning

Stops the ongoing NFC scanning session.

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.stopScanning();

write

Writes the provided NDEF records to the last discovered tag.

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.write({} as WriteTagOptions);

erase

Attempts to erase the last discovered tag by writing an empty NDEF message.

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.erase();

makeReadOnly

Attempts to make the last discovered tag read-only.

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.makeReadOnly();

share

Shares an NDEF message with another device via peer-to-peer (Android only).

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.share({} as ShareTagOptions);

unshare

Stops sharing previously provided NDEF message (Android only).

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.unshare();

getStatus

Returns the current NFC adapter status.

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.getStatus();

showSettings

Opens the system settings page where the user can enable NFC.

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.showSettings();

isSupported

Checks whether the device has NFC hardware support.

Returns true if NFC hardware is present on the device, regardless of whether NFC is currently enabled or disabled. Returns false if the device does not have NFC hardware.

Use this method to determine if NFC features should be shown in your app’s UI. To check if NFC is currently enabled, use getStatus().

import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.isSupported();

Type Reference

StartScanningOptions

Options controlling the behaviour of .

export interface StartScanningOptions {
  /**
   * iOS-only: closes the NFC session automatically after the first successful tag read.
   * Defaults to `true`.
   */
  invalidateAfterFirstRead?: boolean;
  /**
   * iOS-only: custom message displayed in the NFC system sheet while scanning.
   */
  alertMessage?: string;
  /**
   * iOS-only: session type to use for NFC scanning.
   * - `'ndef'`: Uses NFCNDEFReaderSession (default). Only detects NDEF-formatted tags.
   * - `'tag'`: Uses NFCTagReaderSession. Detects both NDEF and non-NDEF tags (e.g., raw MIFARE tags).
   *            Allows reading UID from unformatted tags.
   *            **Requires** the `Near Field Communication Tag Reader Session Formats` entitlement
   *            in your app with the `TAG` format included. Without it the session will fail to
   *            start and the promise will reject with a `NO_NFC` error code.
   * Defaults to `'ndef'` for backward compatibility.
   */
  iosSessionType?: 'ndef' | 'tag';
  /**
   * Android-only: raw flags passed to `NfcAdapter.enableReaderMode`.
   * Defaults to enabling all tag types with skipping NDEF checks.
   */
  androidReaderModeFlags?: number;
}

WriteTagOptions

Options used when writing an NDEF message on the current tag.

export interface WriteTagOptions {
  /**
   * Array of records that compose the NDEF message to be written.
   */
  records: NdefRecord[];
  /**
   * When `true`, the plugin attempts to format NDEF-formattable tags before writing.
   * Defaults to `true`.
   */
  allowFormat?: boolean;
}

ShareTagOptions

Options used when sharing an NDEF message with another device using Android Beam / P2P mode.

export interface ShareTagOptions {
  records: NdefRecord[];
}

NfcStatus

Possible NFC adapter states returned by .

export type NfcStatus = 'NFC_OK' | 'NO_NFC' | 'NFC_DISABLED' | 'NDEF_PUSH_DISABLED';

NfcEvent

Generic NFC discovery event dispatched by the plugin.

export interface NfcEvent {
  type: NfcEventType;
  tag: NfcTag;
}

NfcStateChangeEvent

Event emitted whenever the NFC adapter availability changes.

export interface NfcStateChangeEvent {
  status: NfcStatus;
  enabled: boolean;
}

NdefRecord

JSON structure representing a single NDEF record.

export interface NdefRecord {
  /**
   * Type Name Format identifier.
   */
  tnf: number;
  /**
   * Type field expressed as an array of byte values.
   */
  type: number[];
  /**
   * Record identifier expressed as an array of byte values.
   */
  id: number[];
  /**
   * Raw payload expressed as an array of byte values.
   */
  payload: number[];
}

NfcEventType

Event type describing the kind of NFC discovery that happened.

export type NfcEventType = 'tag' | 'ndef' | 'ndef-mime' | 'ndef-formatable';

NfcTag

Representation of the full tag information returned by the native layers.

export interface NfcTag {
  /**
   * Raw identifier bytes for the tag.
   */
  id?: number[];
  /**
   * List of Android tech strings (e.g. `android.nfc.tech.Ndef`).
   */
  techTypes?: string[];
  /**
   * Human readable tag type when available (e.g. `NFC Forum Type 2`, `MIFARE Ultralight`).
   */
  type?: string | null;
  /**
   * Maximum writable size in bytes for tags that expose NDEF information.
   */
  maxSize?: number | null;
  /**
   * Indicates whether the tag can be written to.
   */
  isWritable?: boolean | null;
  /**
   * Indicates whether the tag can be permanently locked.
   */
  canMakeReadOnly?: boolean | null;
  /**
   * Array of NDEF records discovered on the tag.
   */
  ndefMessage?: NdefRecord[] | null;
}

Source Of Truth

This page is generated from the plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.