@daml/react NPM

@daml/react

React framework for Daml applications

Documentation

Comprehensive documentation for @daml/react can be found here.

Usage

The best way to get you started quickly is to use the create-daml-app template:

daml new --template=create-daml-app my-project-name

and to read the Quickstart Guide.

To get an overview on how to build a Daml application, please read the application architecture overview.

To use @daml/react your application needs to be connected to the JSON API of a Daml ledger. If your JSON API server for the ledger runs on the local host on port 7575, set

"proxy": "http://localhost:7575"

in your package.json and wrap your main component in the DamlLedger component of @daml/react

import DamlLedger from @daml/react

const App: React.FC = () => {
     <DamlLedger
      token: <your authentication token>
      httpBaseUrl?: <optional http base url>
      wsBaseUrl?: <optional websocket base url>
      reconnectThreshold?: <optional delay in ms>
      party: <the logged in party>
    >
      <MainScreen />
    </DamlLedger>
};

Now you can use the following React hooks to interact with a Daml ledger:

`useParty`

useParty returns the party, for which commands are currently send to the ledger.

const party = useParty();

`useLedger`

useLedger returns an instance of the Ledger class of @daml/ledger to interact with the Daml ledger.

const ledger = useLedger();
const newContract = await ledger.create(ContractTemplate, arguments);
const archiveEvent = await Ledger.archive(ContractTemplate, contractId);
const [choiceReturnValue, events] = await ledger.exercise(ContractChoice, contractId, choiceArguments);

`useQuery`

useQuery returns the contracts matching a given query. The query matches for a given contract template and specified field values of the contracts of that template.

const {contracts, loading} = useQuery(ContractTemplate, () => {field: value}, [dependency1,
dependency2, ...]);

If the query is omitted, all visible contracts of the given template are returned.

const {contracts, loading} = useQuery(ContractTemplate);

`useReload`

useReload returns a function to reload the results of queries.

const reload = useReload();
const onClick = reload;

`useStreamQuery`

Deprecated: prefer useStreamQueries

useStreamQuery has the same signature as useQuery, but it constantly refreshes the results.

const {contracts, loading} = useStreamQuery(ContractTemplate, () => {field: value}, [dependency1,
dependency2, ...]);

If the query is omitted, all visible contracts of the given template are returned.

const {contracts, loading} = useStreamQuery(ContractTemplate);

`useStreamQueries`

useStreamQueries is similar to useQuery, except that:

It constantly refreshes the results.
The factory function is expected to return a list of queries, and the resulting set of contracts is the union of all the contracts that match at least one query.
Like useQuery, if no factory function is provided, or if the provided function returns an empty array, the set will contain all contracts of that template.

const {contracts, loading} = useStreamQueries(ContractTemplate,
                                              () => [{field: value}, ...],
                                              [dependency1, dependency2, ...]);

You can additionally pass in an extra function to handle WebSocket connection failures.

`useFetchByKey`

useFetchByKey returns the unique contract of a given template and a given contract key.

const {contract, loading} = useFetchByKey(ContractTemplate, () => key, [dependency1, dependency2, ...]);

`useStreamFetchByKey`

Deprecated: prefer useStreamFetchByKeys

useStreamFetchByKey has the same signature as useFetchByKey, but it constantly keeps refreshing the result.

const {contract, loading} = useStreamFetchByKey(ContractTemplate, () => key, [dependency1, dependency2, ...]);

`useStreamFetchByKeys`

useStreamFetchByKeys takes a template and a factory that returns a list of keys, and returns a list of contracts that correspond to those keys (or null if no contract matches the corresponding key). This hook will keep an open WebSocket connection and listen for any change to the corresponding contracts.

If the factory function returns an empty array, the hook will similarly produce an empty array of contracts.

const {contracts, loading} = useStreamFetchByKeys(ContractTemplate,
                                                  () => [key1, key2, ...],
                                                  [dependency1, dependency2, ...]);

You can additionally pass in an extra function to handle WebSocket connection failures.

Advanced Usage

In order to interact as multiple parties or to connect to several ledgers, one needs to create an extra DamlLedger contexts specific to your requirement.

`createLedgerContext`

createLedgerContext returns another DamlLedger context and associated hooks (useParty, useLedger ... etc) that will look up their connection within that returned context.

@daml/react

Documentation

Usage

useParty

useLedger

useQuery

useReload

useStreamQuery

useStreamQueries

useFetchByKey

useStreamFetchByKey

useStreamFetchByKeys