React

This library was built for applications that use React, it might not be suitable for usage with other libraries or frameworks.

DappProvider

You need to wrap your application with the DappProvider component, which is exported by the library, as we need to create a global Context to be able to manipulate the data.

• import the Provider:

import { DappProvider } from "@elrondnetwork/dapp-core-components";

• Wrap your application with this Provider.

<DappProvider networkConfig={{ network, walletConnectBridge, walletConnectDeepLink }}>

As you might have noticed, the DappProvider accepts a networkConfig object with a couple of keys. This allows using different APIs and different connection providers.

• walletConnectBridge (optional) is a string that is used to establish the connection to walletConnect library.
• walletConnectDeepLink (optional) is a string that will create a deeplink for an application that is used on a mobile phone, instead of generating the login QR code.
• network is a required configuration file that contains the following information about the environment of the application:

{
  id: string;
  egldLabel: string;
  name: string;
  walletAddress: string;
  apiAddress: string;
  gatewayAddress: string;
  explorerAddress: string;
}

UI Wrappers

The library exposes a couple of Components that are connected to the redux store and are used to display various elements
when something happens inside the app:

• TransactionsToastList will display new transactions in nice toasts at the bottom of the screen. This component is fully customizable.

  import {DappUI} from "@elrondnetwork/dapp-core-components";

  <App>
    <DappUI.TransactionsToastList
    toastId?: string,
    title: string,
    shouldRenderDefaultCss?: boolean,
    className?: string
    />
    <Content/>
  </App>

• SignTransactionsModals will show a modal when a new transaction is submitted, prompting the user to verify and sign it.

  import {DappUI} from "@elrondnetwork/dapp-core-components";

<App>
  <DappUI.SignTransactionsModals />
  <Content/>
</App>

NotificationModal Will show a modal to the user with various warnings and errors.

  import {DappUI} from "@elrondnetwork/dapp-core-components";

<App>
  <DappUI.NotificationModal />
  <Content/>
</App>

• DappCoreUIWrapper is a wrapper that needs to be wrapped around the whole tree to namespace the styles inside dapp-core-components Components.

  import {DappCoreUIWrapper} from "@elrondnetwork/dapp-core-components";

<App>
  <DappCoreUIWrapper>
  <Content/>
  </DappCoreUIWrapper>
</App>

Login UI

There are a couple of very handy React components that can be used to login the user and protect certain routes if the user is not logged in.

Under the DappUI object mentioned above, you can find 4 buttons (one for each provider) which abstract away all the logic of loggin in the user and render the default UI. These buttons can be easily customized with a custom css class.
The exported buttons are:

• DappUI.ExtensionLoginButton
• DappUI.WalletConnectLoginButton
• DappUI.LedgerLoginButton
• DappUI.WebWalletLoginButton

example:

<DappUI.ExtensionLoginButton callbackRoute="/dashboard" buttonClassName="extension-login" loginButtonText="Extension login" />

They can also be used with children

<DappUI.ExtensionLoginButton callbackRoute="/dashboard" buttonClassName="extension-login" loginButtonText="Extension login">
  <>
    <icon/>
    <p>Login text</p>
  <>
</DappUI.ExtensionLoginButton

Also, for a quicker setup, the DappUI object exports an DappUI.UnlockPage component, which contains all 4 buttons.

Another handly component is DappUI.AuthenticatedRoutesWrapper, which can be used to protect certain routes and redirect the user to login page if the user is not authenticated.

Import from dapp-core-components:

import { AuthenticatedRoutesWrapper} from "@elrondnetwork/dapp-core-components";

Use with routes:

<AuthenticatedRoutesWrapper
          routes={routes}
          unlockRoute={routeNames.unlock}
        >
          {appContent}
        </AuthenticatedRoutesWrapper>

routes should be an array with objects with a signature similar to this:

{
    path: "/dashboard",
    title: "Dashboard",
    component: Dashboard,
    authenticatedRoute: true,
  }

The important parts that makes this component work are the flag authenticatedRoute: true and the key path, which means that this route should be accessible only to authenticated users.

Login hooks

If needed, the Login UI can be bypassed using a custom UI, and opt in for the login hooks, which expose a trigger function and the login data, ready to be rendered.

These hooks are exposed by the loginServices object, which can be imported from dapp-core-components:

import {loginServices} from @elrondnetwork/dapp-core-components

There are 4 available hooks:

• useExtensionLogin
• useWalletConnectLogin
• useLedgerLogin
• useWebWalletLogin

All hooks have the same respose signature:

return type is as follows:

const [triggerFunction, genericLoginReturnType, customLoginReturnType] = useLoginHook({
    callbackRoute,
    logoutRoute
  });

• initiateLogin is a function that needs to be called for the login flow to be initiated;
• genericLoginReturnType is an object that is exactly the same for all hooks:

{
  error: string,
  isFailed: boolean,
  isLoading: boolean,
  isLoggedIn: boolean
}

• customLoginReturnType is an object that is custom for each hook and returns specific data for that login:

  • null for useExtensionLogin;

  • null for useWebWalletConnect;

  • { uriDeepLink: string, qrCodeSvg: svgElement } for useWalletConnectLogin;

{
  accounts: string[];
  showAddressList: boolean;
  startIndex: number;
  selectedAddress: SelectedAddress | null;
  onGoToPrevPage: () => void;
  onGoToNextPage: () => void;
  onSelectAddress: (address: SelectedAddress | null) => void;
  onConfirmSelectedAddress: () => void;
}

for useLedgerLogin;

Reading User State

Once logged in, the user’s session is persisted and can be read and deleted via a couple of handy functions.

For logging out, the library exposes a simple function called logout, which can be called to clear the user data.

There are 2 ways of reading the user current state: hooks (to be used inside components and for reacting to changes in the data) and simple functions (for reading data outside of React components or inside handlers).

• hooks: useGetLoginInfo, useGetAccountInfo, useGetNetworkConfig;
• functions: getAccount, getAccountBalance, getAccountShard, getAddress, getIsLoggedIn;

Sending Transactions

The API for sending transactions is a function called sendTransactions:

import { sendTransactions } from "@elrondnetwork/dapp-core-components";

It can be used to send a transaction with minimum information:

const { sessionId, error } = await sendTransactions({
    transactions: [
        {
          value: '1000000000000000000',
          data: 'ping',
          receiver: contractAddress
        },
      ],
    });

It returns a Promise that will be fulfilled with {error?: string; sessionId: string | null;}

sessionId is the transaction’s batch id which can be used to track a transaction’s status and react to it.

Tracking a transaction

The library exposes a hook called useTrackTransactionStatus under the object transactionServices.

import {transactionServices} from @elrondnetwork/dapp-core-components;

const transactionStatus = transactionServices.useTrackTransactionStatus({
  transactionId: sessionId,
  onSuccess,
  onFailed,
  onCancelled
});

transactionStatus has the following information about the transaction:

{
  isPending,
  isSuccessful,
  isFailed,
  isCancelled,
  errorMessage,
  status,
  transactions
}

It’s safe to pass in null as a sessionId, so if the transaction wasn’t yet sent, the hook will just return an empty object.

Also, one can use the hook useGetPendingTransactions to get a list of all pending transactions.

Transaction Toasts UI

dapp-core-components also exposes a toast component for tracking transactions that uses the above mentioned hooks and displays toasts with transactions statuses.

The toasts list is exposed via DappUI.TransactionsToastList component and can be used just by rendering it inside the application.

<App>
  <Router/>
  <DappUI.TransactionsToastList />
</App>

Important: This has to be inside the <DappProvider/> children.