Usage with React
Aragon Connect provides a series of utilities that simplify the usage of Aragon Connect in a React environment.
It consists of the <Connect /> component, through which a connection to an organization is described, and a series of hooks: useApp(), useApps(), useOrganization(), usePermissions().
To get started, add the @aragon/connect-react package to your project. It contains all the exports of the @aragon/connect, so you don’t have to install both.
import {Connect,useApps,useOrganization,usePermissions,} from '@aragon/connect-react'function App() {const [org, orgStatus] = useOrganization()const [apps, appsStatus] = useApps()const [permissions, permissionsStatus] = usePermissions()const loading =orgStatus.loading || appsStatus.loading || permissionsStatus.loadingconst error = orgStatus.error || appsStatus.error || permissionsStatus.errorif (loading) {return <p>Loading…</p>}if (error) {return <p>Error: {error.message}</p>}return (<><h1>{org.name}</h1><h2>Apps</h2><ul>{apps.map((app, i) => (<li key={i}>{app.name}</li>))}</ul><h2>Permissions</h2><ul>{permissions.map((permission, i) => (<li key={i}>{String(permission)}</li>))}</ul></>)}ReactDOM.render(<Connect location="myorg.aragonid.eth" connector="thegraph"><App /></Connect>,document.querySelector('main'))
This component is required in order to use the provided hooks.
Props | Type | Description |
|
| The Ethereum address or ENS domain of an Aragon organization. |
|
| Accepts a |
|
| The optional configuration object. |
|
| An EIP-1193 compatible object. |
| The network to connect to. Defaults to |
Props | Type | Description |
returns |
| An array containing the organization and a loading status object. |
Name | Type | Description |
|
| When a string is passed, the app will get searched by address if it starts by |
|
| Same as |
|
| Same as |
returns |
| An array containing a single app from the organization and a loading status object. |
Name | Type | Description |
|
| When a string is passed, apps will get filtered by address if it starts by |
|
| Same as |
|
| Same as |
returns |
| An array containing the organization apps and a loading status object. |
Name | Type | Description |
returns |
| An array containing the organization permissions and a loading status object. |
This utility function makes app connectors available in your React app.
This is how it works at the most basic level:
import { createAppHook, useApp } from '@aragon/connect-react'import connectVoting from '@aragon/connect-voting'// We create a hook corresponding to the app connector. This is usually enough,// since the app connector will inherit from the connection set on <Connect />.const useVoting = createAppHook(connectVoting)function Votes() {const [voting] = useApp('voting')// And this is how we can use it, by passing the app instance and a callback.const [votes] = useVoting(voting, (app) => app.votes())return (<ul>{votes ? (votes.map((vote) => <li key={vote.id}>{formatVote(vote)}</li>)) : (<li>Loading votes…</li>)}</ul>)}
By default, the callback will be called once, and never update afterwards. This can be a problem if you want to reload data depending on the current state. This is why the hook also accept a dependency parameter. It behaves in a very similar way to the useEffect() or useMemo() hooks, except that it doesn’t update the callback when omitted.
This is how you can use it:
import connect from '@aragon/connect'import connectVoting from '@aragon/connect-voting'import { createAppHook, useApp } from '@aragon/connect-react'const useVoting = createAppHook(connectVoting)function App() {const [page, setPage] = useState(0)const [voting] = useApp('voting')const [votes] = useVoting(voting,(app) => app.votes({ first: 10, skip: 10 * page }),[page])return (<div><ul>{votes ? (votes.map((vote) => <li key={vote.id}>{formatVote(vote)}</li>)) : (<li>Loading votes…</li>)}</ul><button onClick={() => setPage(page + 1)}>prev</button><button onClick={() => setPage(page - 1)}>next</button></div>)}
An issue with the previous examples is that we only fetch the data once, instead of receiving updates from it. For example, someone might create a new vote, and it is reasonable to expect an app to reflect that. With the app connectors API, you generally have onX equivalents of the async methods, like votes(filters) and onVotes(filters, callback).
Using them with createAppHook() hooks requires to call the onX equivalent of the async method you want to use, but without passing a callback. App connectors return a partially applied function when the callback is omitted, which createAppHook() takes advantage of by entirely managing the subscription.
import connect from '@aragon/connect'import connectVoting from '@aragon/connect-voting'import { createAppHook, useApp } from '@aragon/connect-react'const useVoting = createAppHook(connectVoting)function App() {const [page, setPage] = useState(0)const [voting] = useApp('voting')// votes will now get updated automaticallyconst [votes] = useVoting(voting,// Note that we are now using onVotes() rather than votes()(app) => app.onVotes({ first: 10, skip: 10 * page }),// When page changes, a new subscription will replace the previous one[page])return (<div><ul>{votes ? (votes.map((vote) => <li key={vote.id}>{formatVote(vote)}</li>)) : (<li>Loading votes…</li>)}</ul><button onClick={() => setPage(page + 1)}>prev</button><button onClick={() => setPage(page - 1)}>next</button></div>)}
