---
description: Learn how use React bindings for the Triplit client in your app.
---

import { Tabs, Tab, Callout } from 'nextra-theme-docs';
import CreateTriplitAppTabs from '../../components/CreateTriplitAppTabs.mdx';

# React

### New projects

The fast way to get started with Triplit is to use Create Triplit App which will scaffold a React application with Triplit. Choose `React` when prompted for the frontend framework.

<CreateTriplitAppTabs />

### Existing projects

If you have an existing React project, you can install the hooks provided by `@triplit/react`:

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']}>

  <Tab>
    ```bash copy
    npm i @triplit/react
    ```
  </Tab>
    <Tab>
    ```bash copy
    pnpm add @triplit/react
    ```
  </Tab>
  <Tab>
    ```bash copy
    yarn add @triplit/react
    ```
  </Tab>
  <Tab>
    ```bash copy
    bun add @triplit/react
    ```
  </Tab>
</Tabs>

## useQuery

The `useQuery` hook subscribes to the provided query inside your React component and will automatically unsubscribe from the query when the component unmounts.

The result of the hook is an object with the following properties:

- `results`: An array of entities that satisfy the query.
- `fetching`: A boolean that will be `true` initially, and then turn `false` when either the local fetch returns cached results or if there were no cached results and the remote fetch has completed.
- `fetchingLocal`: A boolean indicating whether the query is currently fetching from the local cache.
- `fetchingRemote`: A boolean indicating whether the query is currently fetching from the server.
- `error`: An error object if the query failed to fetch.

```tsx filename="app.tsx"
import { useQuery } from '@triplit/react';

const client = new TriplitClient();
const query = client.query('todos');

function App() {
  const { results, fetching, error } = useQuery(client, query);

  if (fetching) return <div>Loading...</div>;
  if (error) return <div>Could not load data.</div>;

  return <div>{results?.map((item) => <div>{item.text}</div>)}</div>;
}
```

<Callout>
  If you're looking for the most multi-purpose loading state, `fetching` is the
  one to use. If you want to ensure that you're only showing the most up-to-date
  data from the server, you can use `fetchingRemote`. If your app is offline and
  should only wait for the cache, use `fetchingLocal`.
</Callout>

## useQueryOne

The `useQueryOne` hook subscribes to a single entity that matches the provided query. You can use this hook inside your React component and it will automatically unsubscribe from updates to the entity when the component unmounts.

The result of the hook is the same as the result of `useQuery`, but the `result` property will only have a single the entity or null.

```tsx copy filename="app.tsx"
import { useQueryOne } from '@triplit/react';

const client = new TriplitClient();

function App() {
  const { result: todo } = useQueryOne(
    client,
    client.query('todos').id('todo-id')
  );

  return <div>{todo.text}</div>;
}
```

## usePaginatedQuery

The `usePaginatedQuery` hook subscribes to the provided query, and exposes helper functions to load the next or previous page of results. It is useful for patterns that load data in pages, such as paginated lists or content browsing applications.

```tsx copy filename="app.tsx"
import { usePaginatedQuery } from '@triplit/react';

const client = new TriplitClient();

function App() {
  const {
    results,
    fetchingPage,
    hasNextPage,
    hasPreviousPage,
    nextPage,
    prevPage,
  } = usePaginatedQuery(
    client,
    client.query('todos').limit(10).order('created_at', 'DESC')
  );

  return (
    <div>
      {results?.map((item) => <div>{item.text}</div>)}
      {fetchingPage && <div>Loading page...</div>}
      {hasPreviousPage && <button onClick={prevPage}>Previous page</button>}
      {hasNextPage && <button onClick={nextPage}>Next page</button>}
    </div>
  );
}
```

For `usePaginatedQuery` to function properly the provided query must have a `limit` set.

## useInfiniteQuery

The `useInfiniteQuery` hook subscribes to the provided query, and exposes helper functions for loading more results. It is useful for patterns that continuously load more data in addition to the existing result set. Chat applications or content browsing applications that load more data as the user scrolls are good use cases for `useInfiniteQuery`.

```tsx copy filename="app.tsx"
import { useInfiniteQuery } from '@triplit/react';

const client = new TriplitClient();

function App() {
  const { results, fetchingMore, hasMore, loadMore } = useInfiniteQuery(
    client,
    client.query('todos').limit(10).order('created_at', 'DESC')
  );

  return (
    <div>
      {results?.map((item) => <div>{item.text}</div>)}
      {fetchingMore && <div>Loading more...</div>}
      {hasMore && <button onClick={loadMore}>Load more</button>}
    </div>
  );
}
```

For `useInfiniteQuery` to function properly the provided query must have a `limit` set. By default `loadMore` will increase the limit by the initial limit set in the query. You can also provide a argument to `loadMore` denoting if you want to increment the limit by a different amount.

## useConnectionStatus

The `useConnectionStatus` hook subscribes to changes to the connection status of the client and will automatically unsubscribe when the component unmounts.

```tsx copy filename="app.tsx"
import { useConnectionStatus } from '@triplit/react';

const client = new TriplitClient();

function App() {
  const connectionStatus = useConnectionStatus(client);

  return (
    <div>
      The client is {connectionStatus === 'OPEN' ? 'connected' : 'disconnected'}
    </div>
  );
}
```
