> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microapp.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CodeGroup>
  ```bash npm theme={null}
  npm install @microapp-io/react
  ```

  ```bash yarn theme={null}
  yarn add @microapp-io/react
  ```

  ```bash pnpm theme={null}
  pnpm add @microapp-io/react
  ```
</CodeGroup>

### 2. Wrap Your App with the Provider

Wrap your application with the `UserPreferencesProvider` component.

```tsx theme={null}
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:

```tsx theme={null}
import { UserPreferencesProvider } from '@microapp-io/react';

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

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

<Warning>
  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.
</Warning>

### 3. Access Theme Preferences

Use the `useUserPreferences` hook to access the user's theme preference.

```tsx theme={null}
import { useUserPreferences } from '@microapp-io/react';

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

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

### 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](https://github.com/pacocoursey/next-themes) to handle theme application:

<CodeGroup>
  ```bash npm theme={null}
  npm install next-themes
  ```

  ```bash yarn theme={null}
  yarn add next-themes
  ```

  ```bash pnpm theme={null}
  pnpm add next-themes
  ```
</CodeGroup>

Configure your Tailwind setup to work with next-themes:

```js theme={null}
// 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:

```tsx theme={null}
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:

```tsx theme={null}
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:

```tsx theme={null}
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:

```tsx theme={null}
// 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;
`;
```

```tsx theme={null}
// 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:

```css theme={null}
/* 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:

```tsx theme={null}
// 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>
  );
}
```