<or-web3> This will be displayed on properly configured <strong>web3</strong> clients. <div slot="noweb3"> This will be displayed on clients that do not support <strong>web3</strong> </div> <div slot="locked"> This will be displayed when <strong>web3</strong> is present, but no user account is available. </div> <div slot="netunsupported"> This will be displayed when <strong>web3</strong> is present and unlocked, but using an unsupported network. </div> <!-- Here we can list the network IDs of supported networks. If no elements with slot="net" are listed, all networks are supported --> <div slot="net">1</div> <div slot="net">42</div> </or-web3>
Web3 ElementFork me on GitHub
yarn add @openrelay/web3-element
At the top level of any dApp built with OpenRelay’s widgets, you’ll find the
<or-web3> tag. It provides two primary functions:
Managing browser support
In dApps, we need to make sure client browsers support Web3. The
tag manages web3 detection, and renders different content depending on the
state of Web3. It lets the page author use Shadow DOM Slots to designate content to show. The slots are as follows:
- noweb3 — Web3 is not present
- locked — The web3 client is locked
- netunsupported — The user is connected to an unsupported network
- [default] — All the necessary conditions are met. The default slot is not specified by a tag; any content not in a specifically designated slot tag are considered part of the default slot.
The content of slots can be arbitrary HTML, allowing you to style the content as you see fit, and provide your users with instructions on how to configure their web3 client to work with your dApp.
<or-web3> tag uses an additional slot, the net slot, to designate
which networks are supported by your dApp. If your dApp should work with any
Ethereum network, you don’t need to designate any net slots. If your dApp is
dependent on contracts on specific networks, you should designate the supported
network with net slots (you can list as many as you need). If your user’s
client is connected to a network not listed in your net slots, the content
of the netunsupported slot will be displayed. The content of the net
slots themselves will never be rendered to a user.
Connecting Child Elements to the Web3 Client
Almost all other widgets in the OpenRelay widget toolkit are dependent on Web3
in one way or another. Managing Web3 clients in each widget can get very
tedious, so we’ve moved that responsibility into the
When an element based on our toolkit is inserted into the page, it emits an
event that will be picked up by the first
<or-web3> tag in that tags
ancestry. That tells the
<or-web3> tag that this element needs a web3 object,
and will need to be notified if the web3 object changes in the future.
<or-web3> tag will detect changes in:
- Web3 availability
- Lock / Unlock status
- Selected networks
- Selected accounts
When these properties change, the will be communicated to child elements by emitting events.
<or-web3> tag can be use to monitor for new blocks. Rather
than having each widget monitor for changes on the blockchain independently,
<or-web3> tag can monitor for new blocks and notify child elements every
time a new block is mined, so that child elements need only check their state
on block boundaries.
Unless you are developing your own widgets, you don’t need to worry about the following API. The widgets that ship with OpenRelay’s toolkit use these APIs, but you don’t need to interact directly with these APIs to use existing widgets.
manualEnable— By default, the web3 tag will request authorization from the browser to access the user’s web3 accounts as soon as the tag loads. If you want to control the presentation of this dialog to your users, add the
manualEnableattribute to your
<or-web3>tag. Note that it is then up to your application to call
<or-web3> tag uses several events to communicate with other DOM elements.
web3-child— An event emitted when a child element is registered. The event must include an attribute
e.detail.elementindicating the newly added element. The
<or-web3>element will respond with a
web3-readyevent, and will notify the registered element on future web3 changes.
e.detail.web3indicating the web3 object to be used for this element and its children. This can be used to override the default use of
subscribe-block— This event is emitted when a child element wishes to subscribe to new block notifications. The event must include an attribute
e.detail.element, which is the element that will be notified when new blocks are mined. When the
<or-web3>tag detects its first
subscribe-blockevent, it begins checking for new blocks at regular intervals.
None of the following events are emitted directly from the
<or-web3> tag triggers them directly on one or more registered
web3-ready— Fired when web3 is confirmed to be available. The web3 object is available at
web3-network— Fired when the web3 network has changed. The network ID is available at
web3-account— Fired when the web3 object’s primary account has changed. the account address is available at