nfc_in_flutter 1.2.0

nfc_in_flutter #

NFC in Flutter is a plugin for reading NFC tags in Flutter. It works on both Android and iOS with a simple stream interface.

⚠️ Currently only NDEF formatted tags are supported.

Usage #

Read NFC tags #

// NFC.readNDEF returns a stream of NDEFMessage
Stream<NDEFMessage> stream = NFC.readNDEF()

stream.listen((NDEFMessage message) {
    print("records: ${message.records.length}");

Read one NFC tag #

NDEFMessage message = await NFC.readNDEF(once: true).first;
print("payload: ${message.payload}");
// once: true` only scans one tag!

Example #

import 'package:nfc_in_flutter/nfc_in_flutter.dart';

class NFCReader extends StatefulWidget {
    _NFCReaderState createState() => _NFCReaderState();

class _NFCReaderState extends State {
    bool _supportsNFC = false;
    bool _reading = false;
    StreamSubscription<NDEFMessage> _stream;

    void initState() {
        // Check if the device supports NFC reading
            .then((bool isSupported) {
                setState(() {
                    _supportsNFC = isSupported;

    Widget build(BuildContext context) {
        if (!_supportsNFC) {
            return RaisedButton(
                child: const Text("You device does not support NFC"),
                onPressed: null,

        return RaisedButton(
            child: Text(_reading ? "Stop reading" : "Start reading"),
            onPressed: () {
                if (_reading) {
                    setState(() {
                        _reading = false;
                } else {
                    setState(() {
                        _reading = true;
                        // Start reading using NFC.readNDEF()
                        _stream = NFC.readNDEF(
                            once: true,
                            throwOnUserCancel: false,
                        ).listen((NDEFMessage message) {
                            print("read NDEF message: ${message.payload}"),
                        }, onError: (e) {
                            // Check error handling guide below

Full example in example directory

Installation #

Add nfc_in_flutter to your pubspec.yaml

  nfc_in_flutter: ^1.2.0

iOS #

On iOS you must add turn on the Near Field Communication capability, add a NFC usage description and a NFC entitlement.

Turn on Near Field Communication Tag Reading #

Open your iOS project in Xcode, find your project's target and navigate to Capabilities. Scroll down to 'Near Field Communication Tag Reading' and turn it on.

Turning on 'Near Field Communication Tag reading'

  • Adds the NFC tag-reading feature to the App ID.
  • Adds the Near Field Communication Tag Reader Session Formats Entitlement to the entitlements file.

from Building an NFC Tag-Reader app

'Turn on Near Field Communication Tag Reading' capability  turned on for a project in Xcode

NFC Usage Description #

Open your ios/Runner/Info.plist file and add a new NFCReaderUsageDescription key. It's value should be a description of what you plan on using NFC for.


Android #

Add the following to your app's AndroidManifest.xml file:

<uses-permission android:name="android.permission.NFC" />

If your app requires NFC, you can add the following to only allow it to be downloaded on devices that supports NFC:

<uses-feature android:name="android.hardware.nfc" android:required="true" />

"What is NDEF?" #

If you're new to NFC you may come to expect a lot of readNFC() calls, but instead you see readNDEF() and NDEFMessage. NDEF is just a formatting standard the tags can be encoded in. There are other encodings than NDEF, but NDEF is the most common one. Currently NFC in Flutter only supports NDEF formatted tags.

Host Card Emulation #

NFC in Flutter supports reading from emulated host cards, however only on Android as Apple doesn't allow it on iOS.

To read from emulated host cards, you need to do a few things.

  • Call readNDEF() with the readerMode argument set to an instance of NFCDispatchReaderMode.
  • Insert the following <intent-filter /> in your AndroidManifest.xml activity:
    <action android:name="android.nfc.action.NDEF_DISCOVERED" />
    <category android:name="android.intent.category.DEFAULT" />

⚠️ Multiple reader modes #

If you start a readNDEF() stream a NFCDispatchReaderMode while another stream is active with the NFCNormalReaderMode, it will throw a NFCMultipleReaderModesException.

Platform differences #

When you call readNDEF() on iOS, Core NFC (the iOS framework that allows NFC reading) opens a little window. On Android it just starts listening for NFC tag reads in the background.

image from Near Field Communication

⚠️ This will also freeze Flutter while open. Please send a Pull Request if you can fix this.

Error handling #

Errors are no exception to NFC in Flutter (hah, get it). The stream returned by NFC.readNDEF() can send 7 different exceptions, and even worse: they are different for each platform!

See the full example in the example directory for an example on how to check for errors.

Exceptions for both platforms #

NDEFReadingUnsupportedException #

Thrown when a reading session is started, but not actually supported.

iOS #

NFCUserCanceledSessionException #

Thrown when the user clicks Cancel/Done core NFC popup. If you don't need to know if the user canceled the session you can start reading with the throwOnUserCancel argument set to false like so: readNDEF(throwOnUserCancel: false)

NFCSessionTimeoutException #

Core NFC limits NFC reading sessions to 60 seconds. NFCSessionTimeoutException is thrown when the session has been active for 60 seconds.

NFCSessionTerminatedUnexpectedlyException #

Thrown when the reading session terminates unexpectedly.

NFCSystemIsBusyException #

Throw when the reading session fails because the system is too busy.

Android #

NFCIOException #

Thrown when a I/O exception occurs. Will for example happen if a tag is lost while being read or a tag could not be connected to.

NDEFBadFormatException #

Thrown when the tag is expected to NDEF formatted, but it is incorrectly formatted.

1.2.0 #

  • Added id property to NDEFMessage which contains the NFC tag's UID
  • Support for more card types on Android

1.1.1 #

  • Bugfix: Android sessions are now closed properly

1.1.0 #

  • Added support for reading from emulated host cards

1.0.0 #

  • First release, woohoo!
  • Support for reading NDEF formatted NFC tags on both Android and iOS


NFC in Flutter example #

An example application to demonstrate NFC in Flutter.

Screenshot of the example app

It is easiest to run the app on an Android device as the iOS simulator can't do NFC and running it on a real device requires a bunch of code signing nonsense.

$ flutter run

Implementation #

The app has a button in the top right corner that starts or stops listening for NFC tags.

    child: Text(reading ? "Stop reading" : "Start reading"),
    onPressed: () {
        if (!reading) {
            setState(() {
                reading = true;
                session = NFC.readNDEF()
                    .listen((tag) {

        } else {
            setState(() {
                reading = false;

When a tag is scanned, it inserts it in a list of scanned tags, which is then rendered in a ListView.

    .listen((tag) (
        setState(() {
            tags.insert(0, tag);

When an error occurs it will show an AlertDialog, unless the error is a NFCUserCanceledSessionException.

    .listen((tag) {
        // ...
    }, onError: (error) {
        if (!(error is NFCUserCanceledSessionException)) {
            // It is up to you how many exceptions you want to check for.
                context: context,
                builder: (context) => AlertDialog(
                    title: const Text("Error!"),
                    content: Text(e.toString()),

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  nfc_in_flutter: ^1.2.0

2. Install it

You can install packages from the command line:

with Flutter:

$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:nfc_in_flutter/nfc_in_flutter.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Aug 21, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.4.0
  • pana: 0.12.19
  • Flutter: 1.7.8+hotfix.4


Detected platforms: Flutter

References Flutter, and has no conflicting libraries.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
flutter 0.0.0
Transitive dependencies
collection 1.14.11 1.14.12
meta 1.1.6 1.1.7
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies