Native NFC tag discovery, reading and writing for Capacitor apps on iOS and Android.
npm install @capgo/capacitor-nfc
Native NFC tag detection, reading, and writing for Capacitor apps on iOS and Android.
Modern Capacitor port of the battle-tested phonegap-nfc plugin, aligned with Capgo conventions and tooling.
- Standard NFC Forum Tags (Type 1-4)
- MIFARE Ultralight - Full support for reading NDEF data from MIFARE Ultralight tags, including EV1 and NTAG variants. The plugin automatically detects MIFARE Ultralight cards and extracts NDEF messages in addition to standard NFC tags.
The most complete documentation will live on the Capgo docs portal. Until then, explore the TypeScript definitions (src/definitions.ts) and run the included example app for a tour of the API.
| Plugin version | Capacitor compatibility | Maintained |
| -------------- | ----------------------- | ---------- |
| v8.\.\ | v8.\.\ | ✅ |
| v7.\.\ | v7.\.\ | On demand |
| v6.\.\ | v6.\.\ | ❌ |
| v5.\.\ | v5.\.\ | ❌ |
> Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
``bash`
npm install @capgo/capacitor-nfc
npx cap sync
Remember to add the required platform configuration:
- Android: ensure your AndroidManifest.xml declares the android.permission.NFC permission.NFCReaderUsageDescription
- iOS: add to your app Info.plist to explain why NFC access is needed.
`ts
import { CapacitorNfc } from '@capgo/capacitor-nfc';
await CapacitorNfc.startScanning({
invalidateAfterFirstRead: false, // keep the session open so we can write later
alertMessage: 'Hold a tag near the top of your device.',
});
const listener = await CapacitorNfc.addListener('nfcEvent', (event) => {
console.info('Tag type:', event.type);
console.info('First record:', event.tag?.ndefMessage?.[0]);
});
// Later, write a simple text record back to the tag
const encoder = new TextEncoder();
const langBytes = Array.from(encoder.encode('en'));
const textBytes = Array.from(encoder.encode('Hello Capgo'));
const payload = [langBytes.length & 0x3f, ...langBytes, ...textBytes];
await CapacitorNfc.write({
allowFormat: true,
records: [
{
tnf: 0x01,
type: [0x54], // 'T'
id: [],
payload,
},
],
});
await listener.remove();
await CapacitorNfc.stopScanning();
`
`ts
import { CapacitorNfc } from '@capgo/capacitor-nfc';
// Use 'tag' session type to read raw (non-NDEF) tags
await CapacitorNfc.startScanning({
iosSessionType: 'tag', // Enable raw tag reading on iOS
alertMessage: 'Hold your card near the device',
});
const listener = await CapacitorNfc.addListener('nfcEvent', (event) => {
console.info('Tag detected:', event.type); // 'tag' or 'ndef'
// Read the UID (identifier) - works for both NDEF and raw tags
if (event.tag?.id) {
const uid = event.tag.id.map(byte => byte.toString(16).padStart(2, '0').toUpperCase()).join(':');
console.info('Tag UID:', uid); // e.g., "04:A1:B2:C3:D4:E5:F6"
}
// If the tag has NDEF data, it will also be available
if (event.tag?.ndefMessage) {
console.info('NDEF records:', event.tag.ndefMessage);
}
});
await listener.remove();
await CapacitorNfc.stopScanning();
`
* startScanning(...)
* stopScanning()
* write(...)
* erase()
* makeReadOnly()
* share(...)
* unshare()
* getStatus()
* showSettings()
* getPluginVersion()
* addListener('nfcEvent', ...)
* addListener('tagDiscovered' | 'ndefDiscovered' | 'ndefMimeDiscovered' | 'ndefFormatableDiscovered', ...)
* addListener('nfcStateChange', ...)
* Interfaces
* Type Aliases
Public API surface for the Capacitor NFC plugin.
The interface intentionally mirrors the behaviour of the reference PhoneGap
implementation to ease migration while embracing idiomatic Capacitor APIs.
`typescript`
startScanning(options?: StartScanningOptions | undefined) => Promise
Starts listening for NFC tags.
| Param | Type |
| ------------- | --------------------------------------------------------------------- |
| options | StartScanningOptions |
--------------------
`typescript`
stopScanning() => Promise
Stops the ongoing NFC scanning session.
--------------------
`typescript`
write(options: WriteTagOptions) => Promise
Writes the provided NDEF records to the last discovered tag.
| Param | Type |
| ------------- | ----------------------------------------------------------- |
| options | WriteTagOptions |
--------------------
`typescript`
erase() => Promise
Attempts to erase the last discovered tag by writing an empty NDEF message.
--------------------
`typescript`
makeReadOnly() => Promise
Attempts to make the last discovered tag read-only.
--------------------
`typescript`
share(options: ShareTagOptions) => Promise
Shares an NDEF message with another device via peer-to-peer (Android only).
| Param | Type |
| ------------- | ----------------------------------------------------------- |
| options | ShareTagOptions |
--------------------
`typescript`
unshare() => Promise
Stops sharing previously provided NDEF message (Android only).
--------------------
`typescript`
getStatus() => Promise<{ status: NfcStatus; }>
Returns the current NFC adapter status.
Returns: Promise<{ status: NfcStatus; }>
--------------------
`typescript`
showSettings() => Promise
Opens the system settings page where the user can enable NFC.
--------------------
`typescript`
getPluginVersion() => Promise<{ version: string; }>
Returns the version string baked into the native plugin.
Returns: Promise<{ version: string; }>
--------------------
`typescript`
addListener(eventName: 'nfcEvent', listenerFunc: (event: NfcEvent) => void) => Promise
| Param | Type |
| ------------------ | ----------------------------------------------------------------- |
| eventName | 'nfcEvent' |
| listenerFunc | (event: NfcEvent) => void |
Returns: Promise<PluginListenerHandle>
--------------------
`typescript`
addListener(eventName: 'tagDiscovered' | 'ndefDiscovered' | 'ndefMimeDiscovered' | 'ndefFormatableDiscovered', listenerFunc: (event: NfcEvent) => void) => Promise
| Param | Type |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| eventName | 'tagDiscovered' \| 'ndefDiscovered' \| 'ndefMimeDiscovered' \| 'ndefFormatableDiscovered' |
| listenerFunc | (event: NfcEvent) => void |
Returns: Promise<PluginListenerHandle>
--------------------
`typescript`
addListener(eventName: 'nfcStateChange', listenerFunc: (event: NfcStateChangeEvent) => void) => Promise
| Param | Type |
| ------------------ | --------------------------------------------------------------------------------------- |
| eventName | 'nfcStateChange' |
| listenerFunc | (event: NfcStateChangeEvent) => void |
Returns: Promise<PluginListenerHandle>
--------------------
#### StartScanningOptions
Options controlling the behaviour of {@link CapacitorNfcPlugin.startScanning}.
| Prop | Type | Description |
| ------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| invalidateAfterFirstRead | boolean | iOS-only: closes the NFC session automatically after the first successful tag read. Defaults to true. |alertMessage
| | iosSessionTypestring | iOS-only: custom message displayed in the NFC system sheet while scanning. |
| | 'ndef''tag' \| 'ndef' | iOS-only: session type to use for NFC scanning. - : 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. Defaults to 'ndef' for backward compatibility. |androidReaderModeFlags
| | NfcAdapter.enableReaderModenumber | Android-only: raw flags passed to . Defaults to enabling all tag types with skipping NDEF checks. |
#### WriteTagOptions
Options used when writing an NDEF message on the current tag.
| Prop | Type | Description |
| ----------------- | ------------------------- | ---------------------------------------------------------------------------------------------------- |
| records | NdefRecord[] | Array of records that compose the NDEF message to be written. |
| allowFormat | boolean | When true, the plugin attempts to format NDEF-formattable tags before writing. Defaults to true. |
#### NdefRecord
JSON structure representing a single NDEF record.
Mirrors the data format returned by the legacy Cordova implementation and
uses integer arrays instead of strings to preserve the original payload
bytes.
| Prop | Type | Description |
| ------------- | --------------------- | ------------------------------------------------------- |
| tnf | number | Type Name Format identifier. |
| type | number[] | Type field expressed as an array of byte values. |
| id | number[] | Record identifier expressed as an array of byte values. |
| payload | number[] | Raw payload expressed as an array of byte values. |
#### ShareTagOptions
Options used when sharing an NDEF message with another device using Android Beam / P2P mode.
| Prop | Type |
| ------------- | ------------------------- |
| records | NdefRecord[] |
#### PluginListenerHandle
| Prop | Type |
| ------------ | ----------------------------------------- |
| remove | () => Promise<void> |
#### NfcEvent
Generic NFC discovery event dispatched by the plugin.
| Prop | Type |
| ---------- | ----------------------------------------------------- |
| type | NfcEventType |
| tag | NfcTag |
#### NfcTag
Representation of the full tag information returned by the native layers.
Supports standard NFC Forum tags as well as MIFARE Ultralight cards (including
EV1 and NTAG variants). NDEF data is automatically extracted from MIFARE Ultralight
tags when available.
| Prop | Type | Description |
| --------------------- | --------------------------------- | -------------------------------------------------------------------------------------- |
| id | number[] | Raw identifier bytes for the tag. |
| techTypes | string[] | List of Android tech strings (e.g. android.nfc.tech.Ndef). |type
| | NFC Forum Type 2string \| null | Human readable tag type when available (e.g. , MIFARE Ultralight). |maxSize
| | isWritablenumber \| null | Maximum writable size in bytes for tags that expose NDEF information. |
| | canMakeReadOnlyboolean \| null | Indicates whether the tag can be written to. |
| | ndefMessageboolean \| null | Indicates whether the tag can be permanently locked. |
| | NdefRecord[] \| null | Array of NDEF records discovered on the tag. |
#### NfcStateChangeEvent
Event emitted whenever the NFC adapter availability changes.
| Prop | Type |
| ------------- | ----------------------------------------------- |
| status | NfcStatus |
| enabled | boolean |
#### NfcStatus
Possible NFC adapter states returned by {@link CapacitorNfcPlugin.getStatus}.
Matches the constants provided by the original PhoneGap NFC plugin for
compatibility with existing applications.
'NFC_OK' | 'NO_NFC' | 'NFC_DISABLED' | 'NDEF_PUSH_DISABLED'
#### NfcEventType
Event type describing the kind of NFC discovery that happened.
- tag: A generic NFC tag (no NDEF payload).ndef
- : A tag exposing an NDEF payload.ndef-mime
- : An NDEF tag that matched one of the MIME type filters.ndef-formatable`: A tag that can be formatted to NDEF.
-
'tag' | 'ndef' | 'ndef-mime' | 'ndef-formatable'