@dfinity/candid-ui

Candid UI

This package provides a web component that can generate an interactive UI for a provided canister. It can be used to interact with canisters that have a Candid interface.

Usage

The web component is called candid-ui. In its basic usage, it takes a canisterId attribute, which is the canister ID of the canister to interact with. If no canisterId is provided, it will render a text input to allow the user to enter a canister ID. The component will also automatically infer a host from the current URL, either selecting a commonly used localhost port if present or mainnet, but this can be overridden by providing a host attribute.

Installation

To use the component, you can either install it from npm:

npm install @dfinity/candid-ui

However, the package is optimized to be used in a script tag, so we recommend using the auto setup script. You can serve the script yourself, or use a CDN like unpkg for convenience:

Example from node_modules:

<script type="module" src="./node_modules/@dfinity/candid-ui/dist/auto.js"></script>
<candid-ui canisterId="rrkah-fqaaa-aaaaa-aaaaq-cai"></candid-ui>

Example from unpkg:

<script type="module" src="https://unpkg.com/@dfinity/candid-ui/dist/auto.js"></script>
<candid-ui canisterId="rrkah-fqaaa-aaaaa-aaaaq-cai"></candid-ui>

or like this:

<script type="module">
  import('https://unpkg.com/@dfinity/candid-ui/dist/auto.js');
</script>

Otherwise, you can manually initialize the component:

<script type="module">
  import('@dfinity/candid-ui').then(({ defineElement }) => {
    defineElement();
  });
</script>
<candid-ui canisterId="rrkah-fqaaa-aaaaa-aaaaq-cai"></candid-ui>

or in a script:

import { defineElement } from '@dfinity/candid-ui';
defineElement();

You can add an event listener to the component to be notified when the component has been initialized:

<script type="module">
  import('@dfinity/candid-ui').then(({ defineElement }) => {
    defineElement();
  });
</script>
<candid-ui></candid-ui>
<script>
  const candidUi = document.querySelector('candid-ui');
  candidUi.addEventListener('ready', () => {
    candidUi.canisterId = 'rrkah-fqaaa-aaaaa-aaaaq-cai';
  });
</script>

Styling

The form comes with a default style, but you can override it by providing your own CSS. Add a style element to with a slot attribute set to style:

<style slot="styles">
  h1 {
    color: red;
  }
</style>

Adjusting Content

The component comes with a default title and description that can be overridden by setting attributes on the component:

<candid-ui
  canisterId="rrkah-fqaaa-aaaaa-aaaaq-cai"
  title="My Canister"
  description="This is my canister interface"
></candid-ui>

You can also provide custom title and description elements using slots:

<candid-ui>
  <h1 slot="title">My Canister</h1>
  <p slot="description">This is my canister interface</p>
</candid-ui>

Full Interface

The component has the following attributes. Each of these can be read or set as a property on the component:

`canisterId`

The canister ID of the canister to interact with. If no canisterId is provided, it will render a text input to allow the user to enter a canister ID.

Default: undefined

Type: string

Example:

candidUi.canisterId = 'rrkah-fqaaa-aaaaa-aaaaq-cai';

<candid-ui canisterId="rrkah-fqaaa-aaaaa-aaaaq-cai"></candid-ui>

`host`

The host to use when connecting to the canister. If no host is provided, it will automatically infer a host from the current URL, either selecting a commonly used localhost port if present or mainnet.

Default: undefined

Type: string

Example:

candidUi.host = 'http://localhost:8080';

<candid-ui host="http://localhost:8080"></candid-ui>

`agent`

The agent to use when connecting to the canister. If no agent is provided, it will automatically create an agent using the provided host. This can only be set using JavaScript.

Default: AnonymousAgent

Type: Agent

Example:

candidUi.agent = new HttpAgent({ host: 'http://localhost:8080', identity: myIdentity });

`identity`

The identity to use when connecting to the canister. If no identity is provided, it will automatically create an agent using the provided host. This can only be set using JavaScript.

Default: undefined

Type: Identity

Example:

candidUi.identity = myIdentity;

`title`

The title to display above the form. If no title is provided, it will use a default title.

Default: "Candid UI"

Type: string

Example:

candidUi.title = 'My Canister';

<candid-ui title="My Canister"></candid-ui>

`description`

The description to display above the form. If no description is provided, it will use a default description.

Default: "Browse and test your API with our visual web interface."

Type: string

Example:

candidUi.description = 'This is my canister interface';

<candid-ui description="This is my canister interface"></candid-ui>

`methods`

The methods to display in the form. If no methods are provided, it will automatically display all the methods from the canister. For the html attribute, you can provide a comma-separated string. Methods will be displayed in the order they are provided.

Default: undefined

Type: Array<string>

Example:

candidUi.methods = ['greet', 'whoami'];

<candid-ui methods="greet, whoami"></candid-ui>

`logLevel`

The log level to use when logging messages. If no logLevel is provided, it will use the default log level.

Default: "none"

Type: "none" | "debug"

Example:

candidUi.logLevel = 'debug';

<candid-ui loglevel="debug"></candid-ui>

Methods

Additionally, the component has the following methods:

setCanisterId(canisterId: string)

Sets the canisterId attribute and updates the form. This is equivalent to setting the canisterId property.

setAgent(agent: Agent)

Sets the agent attribute and updates the form. This is equivalent to setting the agent property.

setIdentity(identity: Identity)

Sets the identity attribute and updates the form. This is equivalent to setting the identity property.

reset()

Resets the form to its initial state.

Events

The component dispatches the following events:

ready

Dispatched when the component has been initialized. This event is dispatched when the component is first rendered, and when the canisterId attribute is set.

error

Dispatched when an error occurs. The event will have a detail property with the error message.

request

Dispatched when the form is submitted. The event will have a detail property with the arguments for the method.

response

Dispatched when the form receives a response. The event will have a detail property with the response.

Development

Setup

git clone
cd candid-ui
npm install

Running

npm start

Building

npm run build