Hooks

React hooks for auth state, RPC execution, real-time events, and context management

useMero

Primary hook — returns the SDK instance and current connection state. Must be called inside MeroProvider.

import { useMero } from '@calimero-network/mero-react';

const {
  mero,              // MeroJs | null — the SDK instance
  isAuthenticated,  // boolean
  isOnline,         // boolean — node reachable
  isLoading,        // boolean — true during initialisation
  nodeUrl,          // string | null
  applicationId,    // string | null
  contextId,        // string | null
  contextIdentity,  // string | null
  connectToNode,    // (url: string) => void
  logout,           // () => void
} = useMero();

Use mero to access the underlying SDK directly. For component-level operations use the purpose-built hooks below.

useExecute

Execute a WASM contract method in a specific context. Requires both contextId and executorId (the identity executing the call).

import { useExecute } from '@calimero-network/mero-react';

function KvStore({ contextId, executorId }: { contextId: string, executorId: string }) {
  const { execute, loading, error } = useExecute(contextId, executorId);

  const getValue = async () => {
    const result = await execute<{ value: string }>('get_value', { key: 'foo' });
    console.log(result?.value);
  };
// execute returns T | null (null if not connected)
// loading and error track the in-flight state
}

// Signature
function useExecute(
  contextId: string | null,
  executorId: string | null,
): {
  execute: <T>(method: string, params?: Record<string, unknown>) => Promise<T | null>;
  loading: boolean;
  error: Error | null;
}

useSubscription

Subscribe to real-time SSE events from one or more contexts. The subscription is automatically set up and torn down with the component lifecycle.

import { useSubscription } from '@calimero-network/mero-react';

function EventFeed({ contextId }: { contextId: string }) {
  const [events, setEvents] = useState<SseEventData[]>([]);

  useSubscription([contextId], (event) => {
    setEvents(prev => [...prev, event]);
  });
}

// Signature
function useSubscription(
contextIds: string[],
callback: (event: SseEventData) => void,
): void

The callback ref is updated on each render so you never capture stale state. Re-subscribes automatically when contextIds change.

Context Hooks

useContexts(applicationId?)

List contexts, optionally filtered by application ID. Returns { data, loading, error }.

useApplicationContexts(applicationId?)

Same as useContexts but returns ApplicationContextRecord[] (contextId + applicationId pairs).

useContextGroup(contextId?)

Fetch the group that a context belongs to.

useContextDiscovery(options)

Discover joinable contexts. Returns ContextDiscoveryState with items and pagination.

useCreateContext()

Returns { createContext, loading, error }. Call createContext(req) to create.

useDeleteContext()

Returns { deleteContext, loading, error }.

useJoinContext()

Returns { joinContext, loading, error }.

Group Hooks

useGroupInfo(groupId?)

Fetch group metadata. Returns { data: GroupInfo | null, loading, error }.

useGroupMembers(groupId?)

List members in a group.

useGroupContexts(groupId?)

List contexts attached to a group.

useGroupInvitations()

List pending group invitations for the current identity.

useGroupCapabilities(groupId?, memberId?)

Fetch capabilities for a member in a group.

useJoinGroup()

Returns { joinGroup, loading, error }.

useDeleteGroup()

Returns { deleteGroup, loading, error }.

useAddGroupMembers()

Add members to a group. Returns { addGroupMembers, loading, error }.

useRemoveGroupMembers()

Remove members from a group.

useSyncGroup()

Trigger group state synchronisation.

useNestGroup()

Nest a group inside a parent group.

useUnnestGroup()

Remove a group from its parent.

useSubgroups()

List subgroups of a group.

useUpgradeGroup()

Upgrade a group to a newer version.

useGroupUpgradeStatus()

Check if a group upgrade is in progress.

useRetryGroupUpgrade()

Retry a failed group upgrade.

useRegisterGroupSigningKey()

useUpdateGroupSettings()

Update group settings (visibility, etc.).

useSetGroupAlias()

Set a display alias for a group.

useSetMemberAlias()

Set a display alias for a member.

useUpdateMemberRole()

Change a member's role in a group.

useSetDefaultCapabilities()

Set default capabilities for new members.

useSetDefaultVisibility()

Set the default context visibility for a group.

useSetTeeAdmissionPolicy()

Configure TEE admission policy for a group.

useDetachContextFromGroup()

Detach a context from its group.

Namespace Hooks

useNamespaces()

List all namespaces. Returns { data: Namespace[], loading, error }.

useNamespace(namespaceId?)

Fetch a single namespace.

useNamespaceGroups(namespaceId?)

List groups inside a namespace.

useNamespaceIdentity(namespaceId?)

Fetch the identity for a namespace.

useNamespacesForApplication(applicationId?)

List namespaces associated with an application.

useCreateNamespace()

Returns { createNamespace, loading, error }.

useDeleteNamespace()

Delete a namespace.

useJoinNamespace()

Join a namespace by invitation.

useCreateNamespaceInvitation()

Create an invitation for a namespace.

useCreateGroupInNamespace()

Create a new group inside a namespace.