MeroProvider

Context provider that creates the SDK instance and manages connection state

Usage

Wrap your application once at the root. All hooks must be used inside a MeroProvider.

import { MeroProvider, AppMode } from '@calimero-network/mero-react';

function Root() {
  return (
    <MeroProvider
      mode={AppMode.SingleContext}
      packageName="com.example.myapp"
    >
      <App />
    </MeroProvider>
  );
}

MeroProviderProps

mode

Required. AppMode — the application mode. Controls how contexts are managed.

packageName

Optional. Your app's package identifier, e.g. 'com.example.myapp'. Used during auth flow.

packageVersion

Optional. Version string for your package. Used during application installation.

registryUrl

Optional. Custom registry URL for package discovery.

timeoutMs

Optional. HTTP request timeout in ms. Passed to the underlying MeroJs instance. Default: 30 000.

children

React children — your application tree.

AppMode

Controls how the provider initialises and which context is active.

AppMode.SingleContext

App operates within a single fixed context. The provider reads contextId from localStorage on mount. Use this for most applications.

AppMode.MultiContext

App can switch between multiple contexts. Context must be selected by the user.

AppMode.Admin

Administrative mode with full node access. Skips application-level context scoping.

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

AppMode.SingleContext // 'single-context'
AppMode.MultiContext // 'multi-context'
AppMode.Admin // 'admin'

ConnectionType

Used with ConnectButton and LoginModal to control which node URLs are offered.

ConnectionType.Remote

Only remote/cloud nodes. Users enter a node URL.

ConnectionType.Local

Only localhost nodes.

ConnectionType.RemoteAndLocal

Both remote and local options available.

ConnectionType.Custom

Custom connection — pass a CustomConnectionConfig object instead.

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

// Use with ConnectButton:
<ConnectButton connectionType={ConnectionType.Remote} />

MeroContextValue — useMero() return type

interface MeroContextValue {
  mero: MeroJs | null;             // SDK instance (null before connected)
  isAuthenticated: boolean;        // true when tokens are present
  isOnline: boolean;              // true when node is reachable
  isLoading: boolean;             // true during initialisation
  nodeUrl: string | null;         // current node URL
  applicationId: string | null;   // current application ID
  contextId: string | null;       // active context ID
  contextIdentity: string | null;// context identity (executor public key)
  connectToNode: (url: string) => void; // set node URL and init
  logout: () => void;                // clear tokens and disconnect
}

SSO — Tokens from URL Hash

When your app is opened from Calimero Desktop, the provider automatically reads tokens from the URL hash via parseAuthCallback(window.location.href) and stores them in the internal token store. You don't need to do anything extra — the provider handles it.

// Desktop opens app at:
// https://app.example.com/#access_token=...&node_url=...&context_id=...&context_identity=...

// MeroProvider reads these automatically on mount.
// useMero().isAuthenticated will be true immediately.

ConnectButton

Drop-in button that shows connection status and handles the full connect/disconnect flow. Uses ConnectionType to decide whether to show the LoginModal or connect directly.

import { ConnectButton, ConnectionType } from '@calimero-network/mero-react';

// Show modal with local + remote options (default)
<ConnectButton />

// Remote-only
<ConnectButton connectionType={ConnectionType.Remote} />

// Skip modal — connect directly to a URL
<ConnectButton connectionType={{ type: ConnectionType.Custom, url: 'http://localhost:4001' }} />

connectionType?

ConnectionType | CustomConnectionConfig. Default: RemoteAndLocal.

className?

CSS class applied to the button element.

style?

React.CSSProperties — inline style override.

theme?

MeroTheme — partial palette override. Forwarded to the embedded LoginModal. Defaults to the green Calimero palette when omitted. See Theming.

States: Disconnected — shows Connect button and opens LoginModal. Connected — shows Connected + dropdown (node URL, Dashboard link, Log out). Reconnecting — disabled button while SSE reconnects.

LoginModal

Modal dialog for node URL selection. Used internally by ConnectButton but also available standalone for custom connect flows.

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

<LoginModal
  isOpen={showModal}
  onConnect={(url) => { connectToNode(url); setShowModal(false); }}
  onClose={() => setShowModal(false)}
  connectionType={ConnectionType.RemoteAndLocal}
/>

isOpen

Required. boolean — controls modal visibility.

onConnect

Required. (url: string) => void — called with the resolved node URL.

onClose

Required. () => void — called when the modal is dismissed.

connectionType

Required. ConnectionType | CustomConnectionConfig — controls which options are shown.

theme?

MeroTheme — partial palette override. Defaults to the green Calimero palette when omitted. See Theming.

Rendered via createPortal at document.body — unaffected by parent overflow or z-index. Uses inline styles, no external CSS dependency.

Theming

Both ConnectButton and LoginModal default to the green Calimero palette used in admin-dashboard, tauri-app, and app-registry. No theme prop is required — pass nothing and you get the default look. Provide a partial MeroTheme to override any subset of tokens.

interface MeroTheme {
  primary?: string; // CTA color — default '#a5ff11'
  primaryHover?: string; // default '#8ed40d'
  primaryText?: string; // text on top of primary — default '#0d1117'
  background?: string; // modal/button surface — default '#0d1117'
  backgroundSecondary?: string;// inputs, info chips — default '#161b22'
  backgroundTertiary?: string; // default '#1c2128'
  border?: string; // default '#30363d'
  text?: string; // default '#e6edf3'
  textSecondary?: string; // default '#8b949e'
  error?: string; // default '#ff6b6b'
  overlay?: string; // modal backdrop — default 'rgba(0, 0, 0, 0.75)'
  radius?: string; // default '8px'
}

Default usage — green Calimero palette:

Override a few tokens — only the keys you provide are changed; the rest keep the defaults:

CSS variable override — same tokens are also exposed as CSS variables on the component root, so global stylesheets work too:

/* anywhere in your app's CSS */
:root {
--mero-accent: #ff4081;
--mero-accent-hover: #e91e63;
}

Helpers — exported alongside the type:

import { defaultMeroTheme, resolveMeroTheme } from '@calimero-network/mero-react';

// defaultMeroTheme: the full green palette as a frozen object
// resolveMeroTheme(partial?): returns a fully populated ResolvedMeroTheme