npm package: @movement-react/prismic
Description: A react library for querying prismic.io's API
Author: Doug Schamberg
Latest version: 1.0.18

# @movement-react/prismic

[Prismic](https://prismic.io) is a headless CMS system that allows you to easily create websites. React
is one of the most popular JavaScript Frameworks. This library aims to help accelerate
development with React and Prismic.

See the [prismic docs](https://prismic.io/docs) for further details on their API's.

<br />
<br />
<br />

## Table of Contents

1. [Installation](#installation)
2. [Getting Started](#getting-started)
3. [Components](#components)
    * [PrismicProvider](#PrismicProvider)
4. [React Hooks](#hooks)
    * [Get multiple documents](#usePrismicQuery)
    * [Get a single document](#usePrismicFetchByID)

<br />
<br />
<br />
<br />

## Installation

`npm install @movement-react/prismic prismic-javascript`

or

`yarn add @movement-react/prismic prismic-javascript`

optionally you can install `prismic-reactjs` to render
their CMS components.

<br />
<br />
<br />

## Getting Started

Below is a quick start to getting setup with the prismic react library.

<br />
<br />

## Requirements

1. You will need access to https://prismic.io
2. Create a new site see the [prismic docs](https://prismic.io/docs) for further details
3. Retrieve your access token from the prismic admin dashboard

<br />
<br />

## Setting Up Your Provider

Within your main component, import and wrap your jsx with the `PrismicProvider` component.

<br />
<br />

```javascript

import { PrismicProvider } from '@movement-react/prismic';

const App = () => {
  const url = `https://${process.env.PRISMIC_DOMAIN}.prismic.io/api/v2`;
  const accessToken = process.env.PRISMIC_ACCESS_TOKEN;
  
  return (
    <PrismicProvider url={url} accessToken={accessToken}>
      <App />
    </PrismicProvider>
  );
}
```

From here you can use the [React Hooks](#hooks) to query your prismic site.

<br />
<br />
<br />
<br />

## Components

1. [PrismicProvider](#PrismicProvider)

<br />
<br />
<br />

## PrismicProvider

A context provider for access the prismic client api. This allows you to query prismic from anywhere within your react application.

<br />
<br />

### PrismicProvider Props

| Name | DataType | Mandatory |
| :----------- | :-----------: | :-----------: |
| url | `string` | <span style="color:red">*</span> |
| accessToken | `string` | <span style="color:red">*</span> |

<br />
<br />

```javascript
import { PrismicProvider } from '@movement-react/prismic';

const App = () => {
  const url = `https://${process.env.PRISMIC_DOMAIN}.prismic.io/api/v2`;
  const accessToken = process.env.PRISMIC_ACCESS_TOKEN;
  
  return (
    <PrismicProvider url={url} accessToken={accessToken}>
      <App />
    </PrismicProvider>
  );
}
```

<br />
<br />
<br />

## Hooks

1. [`usePrismicFetchByID()`](#usePrismicFetchByID)
2. [`usePrismicQuery()`](#usePrismicQuery)

## usePrismicFetchByID

A react hook that fetches a prismic document by the type and UID or ID. 
  
See the [Prismic API](https://prismic.io/docs/technologies/query-by-id-or-uid-reactjs) for further details

<br />
<br />

### usePrismicFetchByID Props

| Name | DataType | Mandatory |
| :----------- | :-----------: | :-----------: |
| type  | `string` | <span style="color:red">*</span> |
| id | `string` | <span style="color:red">*</span> |
| options | `QueryOptions` |

<br />
<br />

```javascript
import { usePrismicFetchByID, PrismicProvider } from '@movement-react/prismic';

const Component = () => {
  const { data, loading } = usePrismicFetchByID('page', 'my-page', { lang: 'en-us' });
  console.log(data) // outputs document with uid 'my-page'
  return (
    <div>{data.id}</div>
  );
}

const App = () => {
  const url = `https://${process.env.PRISMIC_DOMAIN}.prismic.io/api/v2`;
  const accessToken = process.env.PRISMIC_ACCESS_TOKEN;
  
  return (
    <PrismicProvider url={url} accessToken={accessToken}>
      <Component />
    </PrismicProvider>
  );
}
```

<br />
<br />
<br />

## usePrismicQuery

A react hook that fetches documents from the prismic api using predicates.
  
See the [Prismic Predicate API](https://prismic.io/docs/technologies/query-predicates-reference-reactjs) for further details on predicates

<br />
<br />

### usePrismicQuery Props

| Name | DataType | Mandatory |
| :----------- | :-----------: | :-----------: |
| predicates  | `string or string[]` | <span style="color:red">*</span> |
| options | `QueryOptions` |

<br />
<br />

```javascript
import { usePrismicQuery, PrismicProvider } from '@movement-react/prismic';
import Prismic from 'prismic-javascript';

const Component = () => {
  const { data, loading } = usePrismicQuery([
    Prismic.Predicate.at('document.type', 'page')
  ]);
  console.log(data) // outputs an array of documents
  return (
    <div>{
      data.map((result, i) => (
        <div key={i}>{result.id}</di>
      ))}
    </div>
  );
}

const App = () => {
  const url = `https://${process.env.PRISMIC_DOMAIN}.prismic.io/api/v2`;
  const accessToken = process.env.PRISMIC_ACCESS_TOKEN;
  
  return (
    <PrismicProvider url={url} accessToken={accessToken}>
      <Component />
    </PrismicProvider>
  );
}
```