React SDK

Microapp Theming for React Apps

The React SDK enables you to use hooks to retrieve the user’s theme preferences.

Getting Started

1. Install the SDK

Install the SDK with your preferred package manager.

npm

npm install @microapp-io/react

2. Wrap Your App with the Provider

Wrap your application with the UserPreferencesProvider component.

import { UserPreferencesProvider } from '@microapp-io/react';

function App() {
  return <UserPreferencesProvider>{/* Your app code here */}</UserPreferencesProvider>;
}

For local development, use the sandbox feature to test different theme preferences:

import { UserPreferencesProvider } from '@microapp-io/react';

const options = {
  theme: "dark",
};

function App() {
  return (
    <UserPreferencesProvider sandbox={options}>
      {/* Your app code here */}
    </UserPreferencesProvider>
  );
}

The sandbox prop should only be used for local development. Make sure to remove it before deploying to production. In production, theme preferences are controlled by the user through the Microapp platform.

3. Access Theme Preferences

Use the useUserPreferences hook to access the user’s theme preference.

import { useUserPreferences } from '@microapp-io/react';

function ThemeDisplay() {
  const { theme } = useUserPreferences();
  
  return (
    <div>
      <p>Current theme: {theme}</p>
    </div>
  );
}

The theme preference is controlled by the user through the Microapp platform. Your application should respect this preference and adapt accordingly.

4. Create and Apply Theme Styles

Define your theme styles in separate files and apply them based on the user’s theme preference.

1. For Microapp UI and Tailwind Apps

For Microapp UI and Tailwind CSS apps, we recommend using next-themes to handle theme application:

npm

npm install next-themes

Configure your Tailwind setup to work with next-themes:

// tailwind.config.js
module.exports = {
  // Note: Tailwind only supports dark mode in version > 2
  darkMode: 'selector', // If you're using Tailwind < 3.4.1, use 'class' instead
  // ...
};

Then integrate next-themes with your Microapp preferences:

import { useUserPreferences } from '@microapp-io/react';
import { ThemeProvider } from 'next-themes';

function App() {
  const { theme } = useUserPreferences();
  const attribute = undefined; // If you're using Tailwind < 3.4.1, use 'class' instead

  return (
    <ThemeProvider forcedTheme={theme} attribute={attribute}>
      {/* Rest of your app */}
    </ThemeProvider>
  );
}

Or you can set up a two-way sync to update Microapp when the theme changes locally:

import { useUserPreferences } from '@microapp-io/react';
import { ThemeProvider, useTheme } from 'next-themes';

function App() {
  return (
    <ThemeProvider>
      <MicroappThemeSync />
      {/* Rest of your app */}
    </ThemeProvider>
  );
}

function MicroappThemeSync() {
  const { setTheme } = useTheme();
  useUserPreferences({
    onChange: setTheme,
  });

  return null;
}

Then your components can use the theme-based classes:

function ThemedComponent() {
  return (
    <div className="bg-white dark:bg-black text-black dark:text-white">
      <h2>Themed Component</h2>
      <p>This component adapts to the user's theme preference.</p>
    </div>
  );
}

2. For CSS-in-JS Libraries

For styled-components, emotion, or other CSS-in-JS libraries:

// styles.ts
import styled from 'styled-components';
import { themes } from './themes';

export const Container = styled.div`
  background-color: ${props => themes[props.theme || 'light'].background};
  color: ${props => themes[props.theme || 'light'].text};
  padding: 20px;
  border-radius: 8px;
  border: 1px solid ${props => themes[props.theme || 'light'].border};
`;

export const Button = styled.button`
  background-color: ${props => themes[props.theme || 'light'].primary};
  color: ${props => props.theme === 'dark' ? '#000' : '#fff'};
  border: none;
  padding: 10px 20px;
  border-radius: 4px;
  cursor: pointer;
`;

// ThemedComponent.tsx
import { useUserPreferences } from '@microapp-io/react';
import { Container, Button } from './styles';

function ThemedComponent() {
  const { theme } = useUserPreferences();
  
  return (
    <Container theme={theme}>
      <h2>Themed Component</h2>
      <p>This component adapts to the user's theme preference.</p>
      <Button theme={theme}>Click Me</Button>
    </Container>
  );
}

3. For CSS Variables

For applications using CSS variables:

/* styles.css */
:root {
  /* Light theme (default) */
  --background-color: #ffffff;
  --text-color: #333333;
  --primary-color: #0070f3;
  --secondary-color: #ff4081;
  --border-color: #e0e0e0;
}

[data-theme="dark"] {
  --background-color: #121212;
  --text-color: #f5f5f5;
  --primary-color: #90caf9;
  --secondary-color: #f48fb1;
  --border-color: #333333;
}

.container {
  background-color: var(--background-color);
  color: var(--text-color);
  padding: 20px;
  border-radius: 8px;
  border: 1px solid var(--border-color);
}

.button {
  background-color: var(--primary-color);
  color: white;
  border: none;
  padding: 10px 20px;
  border-radius: 4px;
  cursor: pointer;
}

You can then use these styles in your components:

// ThemedComponent.tsx
import { useUserPreferences } from '@microapp-io/react';

function ThemedComponent() {
  const { theme } = useUserPreferences();
  
  return (
    <div
      className="container"
      data-theme={theme}
    >
      <h2>Themed Component</h2>
      <p>This component adapts to the user's theme preference.</p>
    </div>
  );
}