React Hooks

If you want to use it with React instead of using the API Client directly to read data CoreQL comes with two hooks.

Read a Collection

If you want to read a collection of resource use the useCollection hook.

import { useCollection } from 'coreql';

function Users() {
  const { data: users } = useCollection('users');
  // ...
}

This will trigger a GET request against the /users endpoint in your API. By default, it will also have Suspense support enabled, which means the loading state should be handled by the parent using React.Suspense with the fallback prop.

Include Relationships Data

If you need extra data from a relation you can use the include feature of JSON:API

import { useCollection } from 'coreql';

function User({ id }) {
  const { data: users } = useCollection('users', {
    included: ['articles'],
  });
  // ...
}

Now your users will have a data attribute with an array containing the data of the users, and an included attribute with an array of the articles related to those users.

Filter Collection

If you want to get filtered data you can use the filter feature of JSON:API.

import { useCollection } from 'coreql';

function PublishedArticles({ id }) {
  const { data: articles } = useCollection('articles', {
    filters: { status: 'published' },
  });
  // ...
}

Now your articles will have a data attribute with an array containing the data of the articles with the status published.

Sort Collection

If you want to get sorted data you can use the sort feature of JSON:API.

import { useCollection } from 'coreql';

function SortedArticles({ id }) {
  const { data: articles } = useCollection('articles', {
    sort: ['title'],
  });
  // ...
}

Now your articles will have a data attribute with an array containing the data of the articles sorted by title.

Read a Resource

If you want to read a collection of resource use the useCollection hook.

import { useResource } from 'coreql';

function User({ id }) {
  const { data: user } = useResource('users', id);
  // ...
}

This will trigger a GET request against the /users/:id endpoint in your API. By default, it will also have Suspense support enabled, which means the loading state should be handled by the parent using React.Suspense with the fallback prop.

Include Relationships Data

If you need extra data from a relation you can use the include feature of JSON:API

import { useResource } from 'coreql';

function User({ id }) {
  const { data: user } = useResource('users', id, {
    included: ['articles'],
  });
  // ...
}

Now your user will have a data attribute with the user data and an included attribute with an array of the articles related to that user.

Sparse Fields

If you want to get only certain fields of the resource you can use the sparse field feature of JSON:API.

import { useCollection } from 'coreql';

function SortedArticles({ id }) {
  const { data: articles } = useCollection('articles', {
    fields: { articles: ['title'] },
  });
  // ...
}

Now your articles will have a data attribute with an array containing the data of the articles with only the title attribute.

Note: This also works with useResource, in that case, data will be the object of the resource.

Sparse Fields over Relational Data

If you are using included to get data from a related resource you can also use sparse fields.

import { useCollection } from 'coreql';

function SortedArticles({ id }) {
  const { data: articles } = useCollection('articles', {
    included: ['author'],
    fields: { articles: ['title'], users: ['fullName'] },
  });
  // ...
}

Now your articles will have a data attribute with an array containing the data of the articles with only the title attribute, and an included attribute with an array of the users related to those articles with only their full names.

Note: This also works with useResource, in that case, data will be the object of the resource.

Configuring the React Query Hook used Internally

Both, useResource and useCollection are using React Query under the hood if you want to customize the configuration of this hook pass an config argument to the CoreQL hooks.

import { useResource, useCollection } from 'coreql';

function User({ id }) {
  const { data: user } = useResource('users', id, {
    config: {},
  });
  // ...
}

function PublishedArticles({ id }) {
  const { data: articles } = useCollection('articles', {
    config: {},
  });
  // ...
}

In that object, you could pass any valid React Query option. E.g. you could pass the initial data.

import { useResource } from 'coreql';

function User({ id, initialData }) {
  const { data: user } = useResource('users', id, {
    config: { initialData },
  });
  // ...
}