React

If you are using React, you can use 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: A Map containing the results of the query, with entity ids as keys and entities as values.
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.

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.entries().forEach((item) => (
        <div>{item.text}</div>
      ))}
    </div>
  );
}

💡

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.

useEntity

The useEntity hook subscribes to the provided entity inside your React component and 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 results property will only contain the entity you subscribed to.

app.tsx

import { useEntity } from '@triplit/react';
 
const client = new TriplitClient();
 
function App() {
  const { results: entity } = useEntity(client, 'todos', '1');
 
  return <div>{entity.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.

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).orderBy('created_at', 'DESC')
  );
 
  return (
    <div>
      {results.entries().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 continously 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.

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).orderBy('created_at', 'DESC')
  );
 
  return (
    <div>
      {results.entries().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.

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

seed React Native