> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reown.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

## Import the package:

```dart theme={null}
import "package:reown_appkit/reown_appkit.dart";
```

Create your `ReownAppKitModal()` instance, which is your primary class for opening, closing, disconnecting, etc.

Be sure to update the *project ID* and *metadata* with your own.

<Card title="Don't have a project ID?" icon="circle-info" href="https://dashboard.reown.com/?utm_source=cloud_banner&utm_medium=docs&utm_campaign=backlinks">
  Head over to Reown Dashboard and create a new project.
</Card>

## Initialization

In order to initialize `ReownAppKitModal()` instance you must provide a *projectId* and a *metadata*.

```dart theme={null}
// AppKit Modal instance
final _appKitModal = ReownAppKitModal(
  context: context, // required BuildContext
  projectId: '{YOUR_PROJECT_ID}',
  metadata: const PairingMetadata(
    name: 'Example App',
    description: 'Example app description',
    url: 'https://example.com/',
    icons: ['https://example.com/logo.png'],
    redirect: Redirect(
      native: 'exampleapp://',
      universal: 'https://reown.com/exampleapp',
      linkMode: true|false,
    ),
  ),
  enableAnalytics: true,
  siweConfig: SIWEConfig(...),
  featuresConfig: FeaturesConfig(...),
  getBalanceFallback: () async {},
  disconnectOnDispose: true|false,
  customWallets: [
    ReownAppKitModalWalletInfo(
      listing: AppKitModalWalletListing(
        ...
      ),
    ),
  ],
);

// Register here the event callbacks on the service you'd like to use. See `Events` section.

await _appKitModal.init();
```

Alternatively, `ReownAppKitModal()` allows you to create an instance by passing a `ReownAppKit()` object as follows:

```dart theme={null}
// AppKit instance
final appKit = ReownAppKit.createInstance(
  projectId: '{YOUR_PROJECT_ID}',
  metadata: const PairingMetadata(
    name: 'Example App',
    description: 'Example app description',
    url: 'https://example.com/',
    icons: ['https://example.com/logo.png'],
    redirect: Redirect(
      native: 'exampleapp://',
      universal: 'https://reown.com/exampleapp',
      linkMode: true|false,
    ),
  ),
);

// AppKit Modal instance
final _appKitModal = ReownAppKitModal(
  context: context, // required BuildContext
  appKit: appKit,
);

// Register here the event callbacks on the service you'd like to use. See `Events` section.

await _appKitModal.init();
```

The `metadata` object should contain your dApp's name, description, url and icon. Redirect object is optional but *highly recommended*. See next session why.

## Redirect to your dApp

AppKit's metadata object contains a `redirect` option that should be used by the wallet to redirect back to your dapp after connection.

```dart theme={null}
redirect: Redirect(
  // your own custom scheme for deep linking
  native: 'exampleapp://',
  // your own universal link for deep linking, required if you are going to use Link Mode
  universal: 'https://reown.com/exampleapp',
  // enable or disable relay-less communication, see `Link Mode` section
  // won't be used if you decide to support/include non-EVM blockchains
  linkMode: true|false,
),
```

<Note>
  `native:` value must be a valid URI scheme: [https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes#syntax](https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes#syntax)
</Note>

But in order for the redirect mechanism to work, you would also need to add the following in the iOS and Android native sides:

<Tabs>
  <Tab title="iOS">
    1. Locate your `Info.plist` file under `your_project/ios/Runner/` folder.
    2. Locate the `<key>CFBundleURLTypes</key>` section.
    3. Add your schema as `<dict>` entry within the `<array>` object as follows.

    ```xml theme={null}
    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>com.example.yourBundleId</string> <!-- Bundle ID of your app -->
        <key>CFBundleURLSchemes</key>
        <array>
          <!-- your own custom scheme -->
          <!-- Should be the same you set on Redirect.native on Flutter side -->
          <!-- Be mind of removing :// for this step -->
          <string>exampleapp</string>
        </array>
      </dict>
    </array>
    ```
  </Tab>

  <Tab title="Android">
    1. Locate your `AndroidManifest.xml` file under `your_project/android/app/src/main/` folder.
    2. Locate the `<Activity .MainActivity` inside the `<application />` scope.
    3. Add the following intent

    ```xml theme={null}
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- your own custom scheme -->
        <!-- Should be the same you set on Redirect.native on Flutter side -->
        <!-- Be mind of removing :// for this step -->
        <data android:scheme="exampleapp" />
    </intent-filter>
    ```

    <Note>
      If you encounter any issues with your deep linking navigation, especially after upgrading to Flutter 3.27 or later, we kindly encourage you to disable Flutter built-in deep-linking feature as it's been set to true by default, introducing a breaking change: [https://docs.flutter.dev/release/breaking-changes/deep-links-flag-change](https://docs.flutter.dev/release/breaking-changes/deep-links-flag-change)

      So below your `<intent-filter>`, you would add this:

      ```xml theme={null}
      <meta-data android:name="flutter_deeplinking_enabled" android:value="false" />
      ```
    </Note>
  </Tab>
</Tabs>

## Available Buttons

`AppKitModalConnectButton` to open the modal and connect to a wallet or through social options

```dart theme={null}
AppKitModalConnectButton(appKit: _appKitModal)
```

`AppKitModalNetworkSelectButton` to select an available network

```dart theme={null}
AppKitModalNetworkSelectButton(appKit: _appKitModal)
```

`AppKitModalAccountButton` to open account screen once connected

```dart theme={null}
AppKitModalAccountButton(appKitModal: _appKitModal)
```

`AppKitModalAddressButton` shows the address on the current selected network

```dart theme={null}
AppKitModalAddressButton(appKitModal: _appKitModal)
```

`AppKitModalBalanceButton` shows wallet balance on the current selected network

```dart theme={null}
AppKitModalBalanceButton(appKitModal: _appKitModal)
```

To connect to a wallet, you can either use `AppKitModalConnectButton` or `AppKitModalNetworkSelectButton`.

`AppKitModalNetworkSelectButton` will allow the user to pre-select a network before connecting while `AppKitModalConnectButton` will directly show available wallets and social options.

Once connected, `AppKitModalConnectButton` will serve as a Disconnect button while `AppKitModalAccountButton` will show basic account data such as balance and address and will be used to open the Account screen.

Quick example:

```dart theme={null}
Column(
  mainAxisAlignment: MainAxisAlignment.center,
  children: [
    AppKitModalNetworkSelectButton(appKit: _appKitModal),
    AppKitModalConnectButton(appKit: _appKitModal),
    Visibility(
      visible: _appKitModal.isConnected,
      child: AppKitModalAccountButton(appKit: _appKitModal),
    )
  ],
),
```

`AppKitModalAccountButton` is composed of `AppKitModalBalanceButton` and `AppKitModalAddressButton`, and you can use these separately from `AppKitModalAccountButton`

```dart theme={null}
AppKitModalBalanceButton(appKitModal: _appKitModal, onTap: _appKitModal.openModalView);

AppKitModalAddressButton(appKitModal: _appKitModal, onTap: _appKitModal.openModalView);
```

## Custom Buttons

If you'd like, you can also override AppKit's buttons by using the `custom:` property as follows

```dart {3-8} theme={null}
AppKitModalConnectButton(
  appKit: _appKitModal,
  custom: MyCustomButton(
    onPressed: () {
      _appKitModal.openModalView();
    },
    child: const Text('CONNECT WALLET'),
  ),
),
```

`openModalView()` method can accept a "startWidget" argument that you can leverage to open specifics screens of the modal:

```dart theme={null}
// With no options will open default screen depending on the connection status
_appKitModal.openModalView();

// Will open Network Selection screen independently of the connection status
// This option is not needed if you use AppKitModalNetworkSelectButton()
_appKitModal.openModalView(ReownAppKitModalSelectNetworkPage());

// Will open QR Code screen for connection.
// Will work only if not yet connected.
_appKitModal.openModalView(ReownAppKitModalQRCodePage());

// Will open All Wallets screen for connection
// Will work only if not yet connected.
_appKitModal.openModalView(ReownAppKitModalAllWalletsPage());
```