Quickstart

Fifteen minutes, one physical phone, and one cheap NTAG213 sticker. By the end you will have a screen that reads a tag, writes one, and handles cancellation without showing the user an error that is not one.

You need a physical device. Neither the iOS Simulator nor an Android emulator has an NFC controller, so there is nothing for the library to talk to.

1. Install and build

npx expo install react-native-nfc-kit
npx expo prebuild --clean
npx expo run:ios      # or run:android

npx install-expo-modules@latest
npm install react-native-nfc-kit
npx pod-install

With Expo, add the plugin before prebuilding:

app.json

{
  "expo": {
    "plugins": [
      [
        "react-native-nfc-kit",
        { "readerUsageDescription": "Hold your card near the top of the phone" }
      ]
    ]
  }
}

Full detail, including the requirements and the Apple Developer portal step, is in Installation.

2. Check the device before offering the feature

import { nfc } from 'react-native-nfc-kit';

const { supported, enabled } = await nfc.getAvailability();

if (!supported) return; // No NFC hardware. Nothing helps.
if (!enabled) await nfc.openSettings(); // Android only: NFC is switched off.

enabled is a real answer on both platforms here, not a hardcoded true on iOS. On Android the user can switch NFC off while your screen is open, which is why the React binding below subscribes rather than reading once.

3. Read a tag

import { nfc } from 'react-native-nfc-kit';

const message = await nfc.withTag(
  { tech: ['ndef'], timeoutMs: 20_000, ios: { alertMessage: 'Hold your tag near the phone' } },
  async (tag) => {
    if (!tag.is('ndef')) throw new Error('Not an NDEF tag');
    return tag.readNdef();
  },
);

Three things are happening that are worth naming, because they are the whole design:

The tech list is what you are willing to accept

The session only surfaces tags carrying one of the technologies you asked for. On iOS it also decides which reader-session polling options are used.

Narrowing is what makes readNdef exist

Before you narrow, a Tag has an id, a technology list and platform facets — and no technology methods at all. tag.readNdef() on an un-narrowed tag is a compile error, not a runtime surprise.

The session is already closed by the time you read this line

withTag closes on every path out: returning, throwing, an AbortSignal firing, the timeoutMs elapsing, or the platform ending the session underneath. There is no finally for you to forget.

4. Read the records you got

readNdef gives you decoded records, not bytes. Pair each decoder with its guard:

import {
  isUriRecord,
  decodeUriRecord,
  isTextRecord,
  decodeTextRecord,
} from 'react-native-nfc-kit/ndef';

for (const record of message) {
  if (isUriRecord(record)) {
    console.log('link:', decodeUriRecord(record).uri);
  } else if (isTextRecord(record)) {
    const { text, languageCode } = decodeTextRecord(record);
    console.log(`text (${languageCode}):`, text);
  }
}

Calling a decoder on the wrong record type throws invalidArgument rather than returning garbage, so the guard is not optional politeness — it is how you avoid the throw. The NDEF codec covers every record type.

5. Write a tag

Check before you write. A tag that runs out of room part-way through a write is left in a state nobody can read:

import { nfc } from 'react-native-nfc-kit';
import { createUriRecord, encodedMessageLength } from 'react-native-nfc-kit/ndef';

const records = [createUriRecord('https://example.com/ticket/42')];

await nfc.withTag({ tech: ['ndef', 'ndefFormatable'] }, async (tag) => {
  // A factory-fresh tag is often formatable rather than NDEF. Format it.
  if (tag.is('ndefFormatable')) return tag.formatNdef(records);

  if (!tag.is('ndef')) throw new Error('Not an NDEF tag');

  const status = await tag.getNdefStatus();
  if (!status.writable) throw new Error('This tag is locked');
  if (status.capacity < encodedMessageLength(records)) {
    throw new Error('Message too large for this tag');
  }

  await tag.writeNdef(records);
});

Asking for both ndef and ndefFormatable and narrowing on each is the pattern that makes “it works on a used tag and not on a new one” go away.

6. Handle the four errors that are ordinary life

Every rejection is an NfcError with a stable code. Four of them are not bugs and not tag problems — they are what happens on an ordinary Tuesday:

import { NfcError, nfc } from 'react-native-nfc-kit';

try {
  await nfc.withTag({ tech: ['ndef'] }, read);
} catch (error) {
  if (NfcError.is(error, 'userCancelled')) return; // Not a failure. Show nothing.
  if (NfcError.is(error, 'tagLost')) return retry(); // Hold it still, try again.
  if (NfcError.is(error, 'sessionTimeout')) return offerAnotherScan();
  if (NfcError.is(error, 'nfcDisabled')) return nfc.openSettings();
  throw error;
}

Use NfcError.is() rather than instanceof. It brands on the error’s name, so it keeps working when two copies of the package end up in one bundle — which happens, and which breaks instanceof in a way that is very hard to see.

Every code, its cause and its remedy: the error reference.

7. Put it on screen

The React binding handles three things a hand-written version usually does not: unmounting mid-scan cancels the session, a second scan() joins the first rather than opening a second session, and NFC being switched off is reflected without a refresh.

ScanScreen.tsx

import { Button, Text, View } from 'react-native';
import { nfc } from 'react-native-nfc-kit';
import { decodeUriRecord, isUriRecord } from 'react-native-nfc-kit/ndef';
import { useNfcAvailability, useNfcScan } from 'react-native-nfc-kit/react';

export default function ScanScreen() {
  const { ready, supported, loading } = useNfcAvailability();

  const { scan, cancel, scanning, data, error } = useNfcScan(
    async (tag) => {
      if (!tag.is('ndef')) throw new Error('Not an NDEF tag');
      const message = await tag.readNdef();
      const uri = message.find(isUriRecord);
      return uri ? decodeUriRecord(uri).uri : '(no link on this tag)';
    },
    { tech: ['ndef'], timeoutMs: 20_000, ios: { alertMessage: 'Hold your tag near the phone' } },
  );

  if (loading) return <Text>Checking this device</Text>;
  if (!supported) return <Text>This device has no NFC.</Text>;
  if (!ready) return <Button title="Turn NFC on" onPress={() => nfc.openSettings()} />;

  return (
    <View>
      <Button title={scanning ? 'Cancel' : 'Scan a tag'} onPress={scanning ? cancel : scan} />
      {data ? <Text>{data}</Text> : null}
      {error ? <Text>{error.message}</Text> : null}
    </View>
  );
}

Cancelling settles as idle rather than as an error, because the user asked for it and there is nothing to report to them.

On Android there is no system sheet, so nothing appears while scanning is true. Show your own “hold your tag near the phone” state — the button label above is the minimum version of that.

Where to go next

Sessions

withTag is one of three ways to get a tag. The other two are for kiosks and for your own UI.

Smartcards

DESFire and JavaCard, plus the iOS AID declaration without which the tag never arrives.

React hooks

useNfcAvailability, useNfcScan, useNfcTagStream.

Get started

Core concepts

Setup, per use case

Going further

1. Install and build

2. Check the device before offering the feature

3. Read a tag

4. Read the records you got

5. Write a tag

6. Handle the four errors that are ordinary life

7. Put it on screen

Where to go next

Sessions

Tags

Smartcards

React hooks

​1. Install and build

​2. Check the device before offering the feature

​3. Read a tag

​4. Read the records you got

​5. Write a tag

​6. Handle the four errors that are ordinary life

​7. Put it on screen

​Where to go next

Sessions

Tags

Smartcards

React hooks

1. Install and build

2. Check the device before offering the feature

3. Read a tag

4. Read the records you got

5. Write a tag

6. Handle the four errors that are ordinary life

7. Put it on screen

Where to go next