@narmi/tile-client-react

SDK for building Narmi Tiles with React. Provides the client-side wrapper, host communication API, and responsive layout utilities for tiles rendered inside the Narmi banking platform.

Installation

npm install @narmi/tile-client-react

Peer dependency: react ^18.0.0 || ^19.0.0

Quick start

Wrap your tile's root component with <TileClient>. Use the useTileApi hook anywhere inside to communicate with the host app.

import { TileClient, useTileApi } from "@narmi/tile-client-react";
import { useEffect, useState } from "react";

function MyTile() {
  const { refreshAuthorization, openFullView } = useTileApi();
  const [authCode, setAuthCode] = useState<string>("");

  useEffect(() => {
    refreshAuthorization().then(({ code }) => setAuthCode(code || "error"));
  }, []);

  return (
    <div>
      <p>Auth code: {authCode}</p>
      <button onClick={openFullView}>Expand</button>
    </div>
  );
}

export default function App() {
  return (
    <TileClient>
      <MyTile />
    </TileClient>
  );
}

API

<TileClient>

Root wrapper component. Handles height reporting, host initialization, and provides context for useTileApi.

| Prop | Type | Description | | -------------- | ------------------- | ------------------------------------------------------------------------ | | targetOrigin | string (optional) | Origin of the host window for postMessage security. Defaults to "*". | | ...props | div attributes | Passed through to the inner wrapper <div>. |

useTileApi()

Hook that returns the tile-to-host communication API. Must be called inside a <TileClient>.

| Method | Returns | Description | | ------------------------ | ------------------------------------ | ---------------------------------------------------------------------------- | | initialize() | Promise<{ isCompatible: boolean }> | Called automatically on mount. Performs the version handshake with the host. | | setHeight(height) | Promise<{}> | Called automatically via ResizeObserver. Reports content height to the host. | | refreshAuthorization() | Promise<{ code: string \| null }> | Requests a fresh auth code from the host. | | openFullView() | Promise<{ opened: boolean }> | Asks the host to expand the tile to full-screen view. |

<TileSizes>

Responsive layout component that renders different content based on the tile's width.

import { TileSizes } from "@narmi/tile-client-react";

<TileSizes
  small={<CompactView />}
  medium={<StandardView />}
  large={<ExpandedView />}
/>;

| Prop | Type | Description | | -------- | ---------------------- | ----------------------------------------------------------------- | | small | ReactNode | Content rendered below 400px (required). | | medium | ReactNode (optional) | Content rendered at 400px+. Falls back to small. | | large | ReactNode (optional) | Content rendered at 600px+. Falls back to medium, then small. |

The wrapping <div> receives a data-size attribute ("small", "medium", or "large") for CSS targeting.

useTileWidth()

Low-level hook for custom responsive logic.

import { useTileWidth } from "@narmi/tile-client-react";

const { isMedium, isLarge } = useTileWidth();

| Value | Type | Description | | ---------- | --------- | ------------------------------- | | isMedium | boolean | true when tile width >= 400px | | isLarge | boolean | true when tile width >= 600px |

BREAKPOINTS

The pixel thresholds used by useTileWidth and TileSizes:

{ medium: 400, large: 600 }

Local development

Use @narmi/tile-studio to preview and test your tile locally with a simulated host environment.