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

# Getting Started

> Install Anvil2 RN, provide the Carto theme, and render a first component.

Anvil2 RN is the native counterpart to [AI Kit](/docs/kits/ai-kit). Use it for agentic surfaces in React Native apps. Do not apply the Carto theme to an entire screen solely because it contains an AI-powered feature.

## Install

Peer requirements: `react@>=18 <20`, `react-native@>=0.81`, `react-native-svg@^15`, and `react-native-reanimated@>=3.16 <5`. Reanimated is required by `Dialog`, `BottomSheet`, and `PromptBar`.

```bash theme={null}
pnpm add @servicetitan/anvil2-rn react-native-svg react-native-reanimated
```

Or with npm:

```bash theme={null}
npm install --save @servicetitan/anvil2-rn react-native-svg react-native-reanimated
```

Follow the Reanimated [installation guide](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/) for the Babel plugin.

## Provide the Carto theme

Anvil2 RN has no CSS cascade. `CartoThemeProvider` puts the resolved Carto theme on React context, and components read it with `useCartoTheme`. Wrap the root of the agentic surface once.

```tsx theme={null}
import { CartoThemeProvider } from "@servicetitan/anvil2-rn";

export function Root({ children }) {
  return <CartoThemeProvider appearance="auto">{children}</CartoThemeProvider>;
}
```

`appearance="auto"` follows the device color scheme and re-renders when it changes. Use `"light"` or `"dark"` to force an appearance.

`useCartoTheme` returns `{ theme, appearance }`. Without a provider, it falls back to the light theme so components still render in isolated stories and tests.

```tsx theme={null}
import { useCartoTheme } from "@servicetitan/anvil2-rn";

function Surface() {
  const { theme, appearance } = useCartoTheme();
  return null;
}
```

## Quick start

```tsx theme={null}
import { Button, CartoThemeProvider, Text } from "@servicetitan/anvil2-rn";
import { IconPencil } from "@servicetitan/anvil2-icons/react-native";

export function App() {
  return (
    <CartoThemeProvider>
      <Text text="Anvil2 RN" />
      <Button label="Edit" icon={<IconPencil />} onPress={() => {}} />
    </CartoThemeProvider>
  );
}
```

## Icons

Import icons from `@servicetitan/anvil2-icons/react-native`, not from the web package root and not from `lucide-react-native` directly. The allowlist is shared with AI Kit and owned by VizD.

```tsx theme={null}
import { IconPencil, IconPlus } from "@servicetitan/anvil2-icons/react-native";
```

## Telemetry

`Anvil2RNTelemetryProvider` is optional. Without it, instrumented components emit nothing. Mount it around a subtree and pass `onInteraction`. A component emits only when you also set `analyticsId` on that instance.

`meta` carries structural values only (an index, a length). Do not put typed text or other user content there.

```tsx theme={null}
import { Anvil2RNTelemetryProvider, Button } from "@servicetitan/anvil2-rn";

export function App() {
  return (
    <Anvil2RNTelemetryProvider
      onInteraction={(event) => {
        analytics.track(event);
      }}
    >
      <Button label="Save" analyticsId="save" onPress={() => {}} />
    </Anvil2RNTelemetryProvider>
  );
}
```

The handler identity is stable for the provider's lifetime, so an inline `onInteraction` does not re-render instrumented consumers. Thrown or rejected handlers are swallowed so telemetry cannot break the UI.

## Internationalization

Anvil2 RN has no i18n layer yet. Caller-supplied copy (`label`, `text`, and similar) is already in the consumer's locale. Components do not author default English strings for those slots.

## Resources

<Columns cols={2}>
  <Card title="React Native overview" icon="mobile" href="/docs/react-native">
    See how Anvil2 RN docs are organized.
  </Card>

  <Card title="Components" icon="shapes" href="/docs/react-native/components/overview">
    Browse the public component surface.
  </Card>

  <Card title="AI Kit (web)" icon="sparkles" href="/docs/kits/ai-kit/getting-started">
    Read the web kit getting started guide for the matching APIs.
  </Card>

  <Card title="Charts - React Native" icon="chart-column" href="/docs/kits/charts-react-native">
    Implement ECharts with the React Native charts kit.
  </Card>
</Columns>