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.

npm create triplit-app@latest my-app

Existing projects

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

npm i @triplit/react

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.

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>;
}

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.

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.

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.

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.

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>
  );
}