# Editmode for React

## Installation

{% tabs %}
{% tab title="NPM" %}

```
npm install editmode-react
```

{% endtab %}

{% tab title="Yarn" %}

```
yarn add editmode-react
```

{% endtab %}
{% endtabs %}

## Usage

### Step 1:

Within your React app, navigate to the index file within your src directory. Import the Editmode wrapper and wrap your App within.

{% tabs %}
{% tab title="Basic Setup" %}

```jsx
import { Editmode } from "editmode-react";

// 👉 `project_id` can be found in the URL:
// https://editmode.com/projects/{project_id}/chunks

ReactDOM.render(
  <React>
    <Editmode projectId={project_id}>
      <App />
    </Editmode>
  </React>,
  document.getElementById("root")
);
```

{% endtab %}

{% tab title="Specifying a branch" %}

```jsx
import { Editmode } from "editmode-react";

// Branches are used to create separate "versions" of your content, which can
// be useful for staging, running a/b tests, or developing locally on teams.
// Branches are created within the content hub at https://app.editmode.com
// Specifying a branch id when initializing Editmode will load all content
// from that specific branch.

ReactDOM.render(
  <React>
    <Editmode projectId={project_id} branchId={branch_id}>
      <App />
    </Editmode>
  </React>,
  document.getElementById("root")
);
```

{% endtab %}

{% tab title="Specifying default content" %}

```jsx
import { Editmode } from "editmode-react";
import { defaultChunks } from "./data/defaultChunks";

// Editmode is smart about fetching and caching content to ensure that 1. Your
// app/site always remains fast, and 2. Users always see the most recent content.
// While Editmode is capable of loading content direct from our CDN, some 
// customers like to also bundle a resource file within their codebase that will 
// provide content in the event that the API fails. This can 
// be achieved by passing an object with default content to the Editmode provider
// on initialization. The creation of this file can be automated via our API.
// See https://snack.expo.io/@editmode/algolia-demo for an interactive demo
// of this setup

ReactDOM.render(
  <React>
    <Editmode projectId={project_id} defaultChunks={defaultChunks} >
      <App />
    </Editmode>
  </React>,
  document.getElementById("root")
);
```

{% endtab %}
{% endtabs %}

### Step 2:

#### Rendering a chunk:

If you have already created the chunk you would like to render on the Editmode CMS, you can simply pass the identifier as a prop and begin editing. You can provide default content as a fallback should anything go wrong trying to retrieve the data from the API:

{% tabs %}
{% tab title="Render an editable chunk" %}

```jsx
import { Chunk } from "editmode-react";

function Example() {
  return (
    <section>
    
      {/* Reference a standalone chunk using the chunk identifier */}
      <Chunk identifier="cnk_7019e843b76e2d0395ab" />
      
      {/* You can also reference a chunk using its content key */}
      <Chunk identifier="company_name" />
      
      {/* Provide default content when referencing a chunk */}
      {/* Default content is a precaution that will get rendered in 
          the event that the content cannot be served from the Editmode API.
      */}
      <Chunk identifier="company_name">
        Our Company
      </Chunk> 
      
    </section>
  );
}
```

{% endtab %}

{% tab title="Render a hybrid chunk field" %}

```jsx
import { Chunk } from "editmode-react";


function Example() {
  return (
    <section>
      
      {/* Editmode has two types of chunks - "standalone" and "hybrid". 
          Standalone chunks can only store a single piece of content,
          whereas hybrid (or collection) chunks can have many fields.
          These fields are pre-specified in the Content Hub at 
          https://app.editmode.com
      */}
      
      <Chunk identifier="home_hero" field="Headline" />
      <Chunk identifier="home_hero" field="Tagline" />
      <Chunk identifier="home_hero" field="Description" />
      
    </section>
  );
}
```

{% endtab %}

{% tab title="Specify classes" %}

```jsx
import { Chunk } from "editmode-react";

// By default, an editable chunk is rendered to the client as an unstyled <em-span />
// This can cause unwanted behaviour from a styling perspective, so you can tell 
// Editmode to add a class to the wrapper.

function Example() {
  return (
    <section>
      <Chunk identifier="company_name" className="bg-white rounded shadow p-6" />
    </section>
  );
}
```

{% endtab %}
{% endtabs %}

#### Rendering a chunk collection:

Chunk collections are simply a way to group chunks and can be used to render repeatable content. Each collection can contain many properties and each property can hold different types of information.

A good use case example would be creating a "Team Member" collection. It may have `Full Name`, `Title` and `Headshot` properties. Within your React app, you may want to display the name, title and headshot of all your team members (i.e. all chunks within the Team Member collection). You can do this by passing the chunk collection identifier as a prop to the ChunkCollection component. For example...

{% tabs %}
{% tab title="Basic collections w/ inline editing" %}

```jsx
import { ChunkCollection, ChunkFieldValue } from "editmode-react";

function Example() {
  return (
    <section className="testimonials">
    
      {/* Render content from a collection, with inline editing */}
      <ChunkCollection identifier="col_MFxBu6fiTyRM" >   
        <ChunkFieldValue identifier="fld_LscoanYMdCOy" />  
        <ChunkFieldValue identifier="fld_Iq94B0LyQxGc" />   
        <ChunkFieldValue identifier="fld_LyRI6y3v2D8ct" />
      </ChunkCollection>
      
      {/* Use content keys for better readability */}
      <ChunkCollection identifier="testimonials" >   
        <ChunkFieldValue identifier="Name" />  
        <ChunkFieldValue identifier="Role" />   
        <ChunkFieldValue identifier="Comment" />
      </ChunkCollection>
      
      {/* Only render collection items with certain tags */}
      <ChunkCollection identifier="testimonials" tags={["home_testimonials"]}>   
        <ChunkFieldValue identifier="Name" />  
        <ChunkFieldValue identifier="Role" />   
        <ChunkFieldValue identifier="Comment" />
      </ChunkCollection>

    </section>
  );
}
```

{% endtab %}

{% tab title="Going Deeper" %}

```jsx
import { ChunkCollection, ChunkFieldValue, getChunk } from "editmode-react";

// Often, when iterating through a collection of content, your UI will need 
// to access the raw values, instead of rendering inline-editable chunks. 
// For this we use getChunk(), along with ChunkCollection.

function Example() {
  return (
    <section className="meet_the_team">
      <ChunkCollection identifier="navigation_items">
        {(getChunk, chunk) => {
          return (
            if (getChunk(chunk, "Title")) {
            
              {/* Render an editable inline field */}
              <ChunkFieldValue identifier="Title" />
              
              {/* Render a link using the chunk field values*/}
              <a href={getChunk(chunk, "Url")}>
                {getChunk(chunk, "Title")}
              </a>
            }
          )
        }}
      </ChunkCollection>
    </section>
  );
}
```

{% endtab %}
{% endtabs %}

**ChunkCollection Attributes**

| Attribute  | Type           | Description                                                                                                               |
| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------- |
| identifier | `string`       | Takes the id of a collection you want to loop through                                                                     |
| limit      | `int` `string` | `optional` The number of collection items you want to display                                                             |
| tags       | `array`        | `optional` Filter collection items based on tags listed in this prop                                                      |
| className  | `string`       | `optional` Class name(s) that will be added along with “chunks-collection-wrapper” to the main collection `<div>` element |
| itemClass  | `string`       | `optional` Class name(s) that will be added along with “chunks-collection-item–wrapper” to all collection items           |

#### ChunkFieldValue Attributes

| Attribute  | Type     | Description                                                                |
| ---------- | -------- | -------------------------------------------------------------------------- |
| identifier | `string` | Takes the identifier or field\_name of a collection field                  |
| className  | `string` | `optional` Class name(s) that will be added in the chunk `em-span` element |

### Variables

Variables that are created in the Editmode CMS are also supported by passing an object prop as `variables`.

```jsx
function Example() {
  return (
    <section>
      <Editmode projectId="prj_h3Gk3gFVMXbl">
        <Chunk identifier="welcome_message" variables={{ "name": "John" }} />
      </Editmode>
    </section>
  );
}
```

With this, chunks such as `Hello, {{name}}!` will be parsed as `Hello, John!`

### Image Transformations

Editmode is capable of performing all kinds of transformations on your images before they're rendered within your web app or web site &#x20;

The `transformation` attribute is used to perform real-time image transformations to deliver perfect images to the end-users.

```jsx
// This chunk should render an image with 200 x 200 dimension
<Chunk identifier='cnk_23123123' transformation="w-200 h-200" />

// For image inside a collection
<ChunkCollection identifier="col_123...">
    <ChunkFieldValue identifier='Avatar' transformation="w-200 h-200"  />
</ChunkCollection>
```

{% content-ref url="../guides/image-transformation-properties" %}
[image-transformation-properties](https://editmode.gitbook.io/editmode-docs/guides/image-transformation-properties)
{% endcontent-ref %}

### Using the Magic Editor

You can now edit and save all of the chunks in your React app from within the browser - just add `editmode=1` as a query string parameter to the current URL to initialize the Magic Editor.