React Native Materia

A customizable component library implementing the modern Material Design 3 specification for React Native.

---

Overview

React Native Materia is built around the modern Material Design 3 specification, treating color, shape, elevation, and motion as unified primitives. It provides faithful implementations of MD3 components with dynamic color schemes, tonal surfaces, and adaptive contrast levels.

At the center of the library is MateriaProvider, an unopinionated runtime root that coordinates dynamic theming ("light", "dark", "system"), contrast levels ("standard", "medium", "high"), 8dp grid spacing tokens, fifteen typography variants, and global icon registries. Palettes can be generated programmatically from a seed color or imported directly from Material Theme Builder.

All animations and interactions run directly on the UI thread via react-native-reanimated and react-native-gesture-handler for smooth and consistent performance across iOS, Android, and Web. A built-in portal subsystem ensures floating elements like dialogs, menus, and bottom sheets render reliably above navigation hierarchies without context loss or layout clipping.

---

Installation

Install the package into your project using your package manager of choice:

npm install react-native-materia

yarn add react-native-materia

pnpm add react-native-materia

Peer Dependencies

React Native Materia requires several peer dependencies for animations, gesture interactions, and vector iconography:

npm install react-native-reanimated react-native-gesture-handler react-native-svg

yarn add react-native-reanimated react-native-gesture-handler react-native-svg

pnpm add react-native-reanimated react-native-gesture-handler react-native-svg

If you are using Expo, install matching dependency versions with:

npx expo install react-native-reanimated react-native-gesture-handler react-native-svg

---

Quick Start

Wrap your application's root component with MateriaProvider. To support overlay components like modal dialogs and bottom sheets, also wrap your content with PortalProvider and render a root PortalHost:

import React from "react";
import {
  MateriaProvider,
  PortalProvider,
  PortalHost,
} from "react-native-materia";
import { MainNavigation } from "./navigation";

export default function App() {
  return (
    <MateriaProvider>
      <PortalProvider>
        <MainNavigation />
        <PortalHost />
      </PortalProvider>
    </MateriaProvider>
  );
}

Note: MateriaProvider automatically integrates GestureHandlerRootView with full-screen flex layout, so no separate gesture handler root wrapper is required.

Using Components

You can now import and use any pre-built component across your application:

import React from "react";
import { View, StyleSheet } from "react-native";
import { Button } from "react-native-materia";

export const ExampleScreen = () => {
  return (
    <View style={styles.container}>
      <Button
        mode="filled"
        icon="check-rounded"
        onPress={() => console.log("Pressed")}
      >
        Save Changes
      </Button>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
  },
});

---

Documentation

Comprehensive interactive documentation, live component playgrounds, and architecture guides are available in the dedicated documentation app.

To launch the documentation app locally:

npm run docs

Core Architecture

• Getting Started — install dependencies and configure the root provider.
• Provider — manage theme modes, contrast levels, and gesture roots.
• Theming — seed color palettes and Material Theme Builder integration.
• Tokens — spacing, corner shapes, elevation shadows, and motion curves.
• Typography — configure font families across the 15 MD3 type roles.
• Iconography — system icons, custom SVG packs, and icon styling.
• Portal — render dialogs and sheets above navigation layers.

Components

• Button — actions across five emphasis levels.
• IconButton — compact icon-only actions with ripple feedback.
• Icon — scalable vector icons with automatic accessibility support.
• List — standard and segmented rows with content slots.

---

Design Guidelines

While React Native Materia implements the tokens, components, and motion curves of the design system, creating an effective user experience requires adhering to the official Material Design 3 Guidelines.

Structural decisions regarding screen composition, visual hierarchy, choosing appropriate component variants (such as filled vs. outlined buttons, or modal bottom sheets vs. dialogs), and spatial layout should always be guided by the official specification.

---

License

MIT © andreevgs