Skip to main content

UI Elements


We strongly recommend keeping the default UI Elements. Consistent UI helps users to interact with different dApps more easily.

The default UI elements have been designed with all wallets and user setups in mind. It handles a lot of cases that are not obvious at first glance. If you really must overwrite the default UI.

Custom UI Guidelines

  1. When the user wants to connect to a wallet, a selection of wallets must be shown. The selection depends on the device the user is using and should display different options on different devices.

On desktop there is only one view with some wallets and the QR code.
Beacon Pairing
  1. Every message sent by the dApp should trigger a persistent element on screen, indicating that a request is in progress.
Beacon Loading
  • If no message has been received for a certain amount of time (eg. 5 seconds), the UI should indicate that there are potential connection issues. The dApp should NOT do any automatic action at this point, because some delays are normal, especially when working with wallets that communicate over the P2P network.
  • In the UI element that is shown, the user SHOULD have the option to reset his connection, meaning to disconnect a wallet. This will abort the whole flow. The user can start the action again, which will now trigger a new "pairing" alert because the previous connection was reset.
Beacon Loading Open
  1. Once the Wallet receives the request, it will immediately send back an Acknowledgement Message. When this message is received in the dApp, the dApp knows that the connection is still valid and the user can handle the request. The persistent UI element that is shown on screen should now be updated, indicating that we are waiting for user input on the wallet.
Beacon Awaiting
  1. When the response is received, the persistent element can be removed again and the successful (or error) response can be displayed to the user and the application flow can be continued.

Overwriting Default UI elements

You can overwrite all of the default UI elements by doing the following.

Live Editor

You can also add your own logic to specific events and still keep the original behaviour.

The same can be achieved without overwriting the default event handler by subscribing to an event. This method is preferred, if possible.

Live Editor

The closing of the pairing alert can not be listened to by default. The reason for this is the delay in the P2P connections. It is possible that a user scans the pairing QR code with his wallet and then closes the alert while waiting for the connection to be established. If the dApp interprets the "closing" of the alert as an abort, and a few seconds later the connection is established successfully, the behaviour could be unexpected.

If you still want to be notified of the closing of the pairing window, you can do it in the following way, while keeping the default behaviour.

Live Editor