Install and wire the React packages

[⏱️ ~3 min] Install the three MDK React packages, wrap your app in MdkProvider, and wire headless stores

This page walks through the minimum integration of the MDK UI toolkit into a React application. Reference and component pages link here as their shared installation prerequisite.

Prerequisites

Node.js >=24
npm >=11
React 19+ and react-dom 19+

Install

npm install \
  @tetherto/mdk-react-devkit \
  @tetherto/mdk-react-adapter \
  @tetherto/mdk-ui-foundation

Wrap your app in <MdkProvider> from @tetherto/mdk-react-adapter when using connected foundation components or adapter store hooks.

Wrap your app in MdkProvider

MdkProvider sets up the TanStack QueryClient and the API base URL context. It is required for foundation hooks and components that read shared app state.

// main.tsx
import { MdkProvider } from '@tetherto/mdk-react-adapter'
import '@tetherto/mdk-react-devkit/styles.css'

ReactDOM.createRoot(rootElement).render(
  <MdkProvider apiBaseUrl="https://app-node.example.com">
    <App />
  </MdkProvider>,
)

apiBaseUrl must point at a Gateway that mounts the routes your pages read. A Gateway serves only what the apps it declares provide, so the endpoints behind these hooks come from an app you ship. Writing an app's routes and declaring it in your stack covers that side.

Use the adapter hooks inside React

Each hook subscribes the component to the relevant Zustand store and re-renders only when the selected slice changes.

import { useAuth, useDevices } from '@tetherto/mdk-react-adapter'

const Toolbar = () => {
  const { permissions } = useAuth()
  const { selectedDevices } = useDevices()
  // ...
}

Or read / write stores directly outside React

The vanilla stores expose getState() / setState() so utility code, side-effect handlers, and tests can interact with the same source of truth.

import { devicesStore, timezoneStore } from '@tetherto/mdk-ui-foundation'

// Outside React (utilities, sagas, etc.) you can read/write directly:
devicesStore.getState().setSelectedDevices([])
timezoneStore.getState().setTimezone('UTC')

Theme via design tokens and @layer mdk

The compiled stylesheet declares @layer base, mdk, app, so unlayered or @layer app styles in your application always win against devkit component styles. MDK ships with --mdk-color-primary: #f7931a; override tokens in :root only when reskinning.

/* app.css — imported AFTER @tetherto/mdk-react-devkit/styles.css */
:root {
  --mdk-color-primary: #f7931a;
  --mdk-radius: 6px;
}

@layer app {
  .mdk-button--variant-primary { letter-spacing: 0.04em; }
}

Next steps

Browse the state, component, and utility hooks: what each hook selects and re-renders on
Browse the component reference: building blocks and mining-domain components, with props and usage