Getting Started

This guide explains how to integrate the @yourmd/yourmd-react-native SDK into your React Native application.

Installation

Install the SDK package and its peer dependencies:

npm install @yourmd/yourmd-react-native

Peer Dependencies

Ensure the following peer dependencies are installed in your project:

npm install react react-native react-native-gesture-handler

The SDK also depends on the following packages which are bundled with it:

react-native-svg

If your project does not already include these, install them as well:

npm install react-native-svg

Fonts

The SDK uses custom fonts that must be loaded before rendering any SDK components. The required font files are:

Biennale-SemiBold (.otf)
Biennale-Regular (.otf)
LibreFranklin-Regular (.ttf)

These fonts will be provided to you separately. Load them using your preferred font loading method. For example, with Expo:

import { useFonts } from "expo-font";

function FontLoader({ children }: { children: React.ReactNode }) {
  const [loaded, error] = useFonts({
    "Biennale-SemiBold": require("./assets/fonts/biennale-semibold.otf"),
    "Biennale-Regular": require("./assets/fonts/biennale-regular.otf"),
    "LibreFranklin-Regular": require("./assets/fonts/librefranklin-regular.ttf"),
  });

  if (!loaded && !error) {
    return null;
  }

  return children;
}

For bare React Native projects, you can use react-native-asset or link the fonts via your native configuration.

Using Your Own Fonts

If you prefer to use your own fonts instead of the defaults, you can do so by loading your custom font files and then updating the theme's fonts property to point to the new font family names. This tells the SDK to use your fonts across all components.

import { useFonts } from "expo-font";
import { createTheme } from "@yourmd/yourmd-react-native";

// 1. Load your custom fonts
function FontLoader({ children }: { children: React.ReactNode }) {
  const [loaded, error] = useFonts({
    "MyFont-Bold": require("./assets/fonts/MyFont-Bold.ttf"),
    "MyFont-Regular": require("./assets/fonts/MyFont-Regular.ttf"),
  });

  if (!loaded && !error) return null;
  return children;
}

// 2. Create a theme that maps the font tokens to your font family names
const theme = createTheme({
  fonts: {
    titleLarge: "MyFont-Bold",
    titleSmall: "MyFont-Bold",
    headerLarge: "MyFont-Bold",
    headerSmall: "MyFont-Bold",
    bodyLarge: "MyFont-Regular",
    bodySmall: "MyFont-Regular",
    bodyCaption: "MyFont-Regular",
    buttonLarge: "MyFont-Bold",
    buttonSmall: "MyFont-Bold",
  },
});

The font token names you provide must match exactly what you register when loading the fonts. See the Theming page for the full list of font tokens and what each one controls.

Configuration

The SDK requires API credentials to authenticate with the YourMD service. You will receive these from YourMD when you register as a partner.

import { AssessmentConfig } from "@yourmd/yourmd-react-native";

const config: AssessmentConfig = {
  baseUrl: "https://your-api-base-url.com/api",
  apiKey: "your-api-key",
  partnerId: "your-partner-id",
  secret: "your-secret",
};

Property	Description
`baseUrl`	The base URL for the YourMD API
`apiKey`	Your API key provided by YourMD
`partnerId`	Your partner identifier provided by YourMD
`secret`	Your partner secret provided by YourMD

Providers

The SDK requires two providers to be wrapped around your application:

ThemeProvider — Supplies the design system theme to all SDK components.
AssessmentProvider — Manages authentication, session state, and the assessment lifecycle. Requires your API configuration.

Both providers must be ancestors of any SDK feature component.

Basic Setup

Here is a minimal example integrating the SDK into your app:

import {
  AssessmentConfig,
  AssessmentProvider,
  ThemeProvider,
  createTheme,
  Assessment,
} from "@yourmd/yourmd-react-native";

const config: AssessmentConfig = {
  baseUrl: "https://your-api-base-url.com/api",
  apiKey: "your-api-key",
  partnerId: "your-partner-id",
  secret: "your-secret",
};

// Use the default theme, or pass overrides to createTheme()
const theme = createTheme();

function App() {
  return (
    <ThemeProvider theme={theme}>
      <AssessmentProvider config={config}>
        <Assessment
          onExit={() => {
            // Handle when the user exits the assessment
            console.log("User exited the assessment");
          }}
        />
      </AssessmentProvider>
    </ThemeProvider>
  );
}

Feature Components

The SDK provides two feature components. Both accept an optional onExit callback. When provided, a back button is displayed on the first screen of the flow, allowing the user to exit. If onExit is omitted, no back button is shown.

Assessment — A step-by-step, form-based assessment flow.
Chat — A conversational, chat-based interface for the same flow.

See each component's page for usage details.

Choosing Between Assessment and Chat

Both components go through the same underlying assessment flow and produce the same health report. The difference is purely in the user experience:

Assessment — Traditional form layout with dedicated screens for each step.
Chat — Conversational messaging interface with scrollable history.

Use whichever best fits your application's design.

Complete Example

A full example with font loading, theme customisation, and the Chat component:

import { useFonts } from "expo-font";
import {
  AssessmentConfig,
  AssessmentProvider,
  ThemeProvider,
  createTheme,
  Chat,
} from "@yourmd/yourmd-react-native";

const config: AssessmentConfig = {
  baseUrl: "https://your-api-base-url.com/api",
  apiKey: "your-api-key",
  partnerId: "your-partner-id",
  secret: "your-secret",
};

const theme = createTheme({
  colors: {
    "neutral/neutral-black": "#1A1A2E",
  },
});

function FontLoader({ children }: { children: React.ReactNode }) {
  const [loaded, error] = useFonts({
    "Biennale-SemiBold": require("./assets/fonts/biennale-semibold.otf"),
    "Biennale-Regular": require("./assets/fonts/biennale-regular.otf"),
    "LibreFranklin-Regular": require("./assets/fonts/librefranklin-regular.ttf"),
  });

  if (!loaded && !error) return null;
  return children;
}

export default function App() {
  return (
    <FontLoader>
      <ThemeProvider theme={theme}>
        <AssessmentProvider config={config}>
          <Chat
            onExit={() => {
              // Handle exit — e.g. navigate to home screen
            }}
          />
        </AssessmentProvider>
      </ThemeProvider>
    </FontLoader>
  );
}