Usage with React

Search…
Usage with React
Introduction
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.
Usage
1
import {
2
  Connect,
3
  useApps,
4
  useOrganization,
5
  usePermissions,
6
} from '@aragon/connect-react'
7
​
8
function App() {
9
  const [org, orgStatus] = useOrganization()
10
​
11
  const [apps, appsStatus] = useApps()
12
  const [permissions, permissionsStatus] = usePermissions()
13
​
14
  const loading =
15
    orgStatus.loading || appsStatus.loading || permissionsStatus.loading
16
  const error = orgStatus.error || appsStatus.error || permissionsStatus.error
17
​
18
  if (loading) {
19
    return <p>Loading…</p>
20
  }
21
​
22
  if (error) {
23
    return <p>Error: {error.message}</p>
24
  }
25
​
26
  return (
27
    <>
28
      <h1>{org.name}</h1>
29
​
30
      <h2>Apps</h2>
31
      <ul>
32
        {apps.map((app, i) => (
33
          <li key={i}>{app.name}</li>
34
        ))}
35
      </ul>
36
​
37
      <h2>Permissions</h2>
38
      <ul>
39
        {permissions.map((permission, i) => (
40
          <li key={i}>{String(permission)}</li>
41
        ))}
42
      </ul>
43
    </>
44
  )
45
}
46
​
47
ReactDOM.render(
48
  <Connect location="myorg.aragonid.eth" connector="thegraph">
49
    <App />
50
  </Connect>,
51
  document.querySelector('main')
52
)
Copied!
API
<Connect />
This component is required in order to use the provided hooks.
Props
Type
Description
location
String
The Ethereum address or ENS domain of an Aragon organization.
connector
Connector or [String, Object] or String
Accepts a Connector instance, and either a string or a tuple for embedded connectors and their config.
options
Object
The optional configuration object.
options.ethereum
EthereumProvider
An EIP-1193 compatible object.
options.network
​Networkish​
The network to connect to. Defaults to 1.
useOrganization()
Props
Type
Description
returns
[Organization | null, { loading: boolean, error: null | Error, retry: Function }]
An array containing the organization and a loading status object.
useApp(appFilters)
Name
Type
Description
appFilter
String or Object (optional)
When a string is passed, the app will get searched by address if it starts by 0x, and by appName otherwise. See appFilter.address and appFilter.appName to set them explicitly. For the time being, only one type of filter can get passed at a time.
appFilter.address
String
Same as appFilter, but makes the selection by address explicit.
appFilter.appName
String
Same as appFilter, but makes the selection by appName explicit.
returns
[App | null, { loading: boolean, error: null | Error, retry: Function }]
An array containing a single app from the organization and a loading status object.
useApps(appFilters)
Name
Type
Description
appFilter
String or String[] or object (optional)
When a string is passed, apps will get filtered by address if it starts by 0x, and by appName otherwise. When an array is passed, the first entry determines the type of filter. See appFilter.address and appFilter.appName to set them explicitly. For the time being, only one type of filter can get passed at a time.
appFilter.address
String or String[]
Same as appFilter, but makes the selection by address explicit.
appFilter.appName
String or String[]
Same as appFilter, but makes the selection by appName explicit.
returns
[App[], { loading: boolean, error: null | Error, retry: Function }]
An array containing the organization apps and a loading status object.
usePermissions()
Name
Type
Description
returns
[Permission[], { loading: boolean, error: null | Error, retry: Function }]
An array containing the organization permissions and a loading status object.
createAppHook()
This utility function makes app connectors available in your React app.
This is how it works at the most basic level:
1
import { createAppHook, useApp } from '@aragon/connect-react'
2
import connectVoting from '@aragon/connect-voting'
3
​
4
// We create a hook corresponding to the app connector. This is usually enough,
5
// since the app connector will inherit from the connection set on <Connect />.
6
const useVoting = createAppHook(connectVoting)
7
​
8
function Votes() {
9
  const [voting] = useApp('voting')
10
​
11
  // And this is how we can use it, by passing the app instance and a callback.
12
  const [votes] = useVoting(voting, (app) => app.votes())
13
​
14
  return (
15
    <ul>
16
      {votes ? (
17
        votes.map((vote) => <li key={vote.id}>{formatVote(vote)}</li>)
18
      ) : (
19
        <li>Loading votes…</li>
20
      )}
21
    </ul>
22
  )
23
}
Copied!
Dependency array
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:
1
import connect from '@aragon/connect'
2
import connectVoting from '@aragon/connect-voting'
3
import { createAppHook, useApp } from '@aragon/connect-react'
4
​
5
const useVoting = createAppHook(connectVoting)
6
​
7
function App() {
8
  const [page, setPage] = useState(0)
9
  const [voting] = useApp('voting')
10
​
11
  const [votes] = useVoting(
12
    voting,
13
    (app) => app.votes({ first: 10, skip: 10 * page }),
14
    [page]
15
  )
16
​
17
  return (
18
    <div>
19
      <ul>
20
        {votes ? (
21
          votes.map((vote) => <li key={vote.id}>{formatVote(vote)}</li>)
22
        ) : (
23
          <li>Loading votes…</li>
24
        )}
25
      </ul>
26
      <button onClick={() => setPage(page + 1)}>prev</button>
27
      <button onClick={() => setPage(page - 1)}>next</button>
28
    </div>
29
  )
30
}
Copied!
Subscriptions
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.
1
import connect from '@aragon/connect'
2
import connectVoting from '@aragon/connect-voting'
3
import { createAppHook, useApp } from '@aragon/connect-react'
4
​
5
const useVoting = createAppHook(connectVoting)
6
​
7
function App() {
8
  const [page, setPage] = useState(0)
9
  const [voting] = useApp('voting')
10
​
11
  // votes will now get updated automatically
12
  const [votes] = useVoting(
13
    voting,
14
​
15
    // Note that we are now using onVotes() rather than votes()
16
    (app) => app.onVotes({ first: 10, skip: 10 * page }),
17
​
18
    // When page changes, a new subscription will replace the previous one
19
    [page]
20
  )
21
​
22
  return (
23
    <div>
24
      <ul>
25
        {votes ? (
26
          votes.map((vote) => <li key={vote.id}>{formatVote(vote)}</li>)
27
        ) : (
28
          <li>Loading votes…</li>
29
        )}
30
      </ul>
31
      <button onClick={() => setPage(page + 1)}>prev</button>
32
      <button onClick={() => setPage(page - 1)}>next</button>
33
    </div>
34
  )
35
}
Copied!
Guides - Previous
Aragon Basics
Next - Advanced
Custom Subgraph queries
Last modified 8mo ago
Copy link
Contents