SDKs

Ditto's SDKs helps teams surface the copy pulled from Ditto in their app.

React SDK

ditto-react is a package to pull in product copy from Ditto into React applications.

You can use this in conjunction with the JSON file fetched from the Ditto API (directly or by using our CLI), or from our Export in the web app.

Getting Started

Install Ditto's React SDK with either NPM or Yarn.

npm install ditto-react
yarn add ditto-react

Usage

DittoProvider Props

DittoProvider is used to wrap anywhere in your app you'd like to use Ditto components. Use DittoProvider to specify the source of any Ditto components inside.

Prop

Type

Description

source

JSON (required)

product copy to be used by Ditto wherever DittoProvider wraps — see Source (link to bottom) for more info

DittoProvider Example

import source from "/.ditto/text.json";
<DittoProvider source={source}>
{/* insert any app components here,
including Ditto components and regular
React components */}
</DittoProvider>

Ditto Props

Ditto is used to fetch specific text, blocks, and frames from the source.

Prop

Type

Description

Example

frameId

string (optional)

ID of a frame in Ditto

blockId

string (optional)

ID of a block in Ditto

textId

string (optional)

ID of a single text item in Ditto

filters

object (option)

object of filters for text items returned. Currently supports a single parameter: tags, an array of tag strings

{ tags: ["SELECTS"]}

Example: Single Text

The Ditto component can be used to fetch a specific text item from the Ditto project using its unique ID. Note that you can edit IDs for text, blocks, and frames directly in our web-app.

<Ditto textId="text_601cc35c5bsdfe42cc3f6f8ac59"/>

Example: Fetch Block

You can also fetch an entire Block in Ditto at once by specifying the frameId and the blockId.

It will return as an entire JSON object of the frame. You can pull out specific IDs of text you'd like to pass to its children.

<Ditto frameId="frame_601cc35d5be42cc3f6f8ad15" blockId="hero">
{({
hero_h1, text_601cc35c5be42cc3f6f8ac46, hero_cta
}) => (
<div>
<h1>{hero_h1}</h1>
<h2>{text_601cc35c5be42cc3f6f8ac46}</h2>
<button>{hero_cta}</button>
</div>
)}
</Ditto>

You can also iterate through the entire block (just as you can with any other object) to display each one.

<Ditto
frameId="header"
blockId="navigation"
>
{( block ) => {
return Object.keys(block).map((id) => (
<div key={block[id]}>{block[id]}</div>
));
}}
</Ditto>

Example: Fetch Frame

You can also fetch an entire Block in Ditto at once by just specifying the frameId. With it, you can fetch specific blocks, or iterate through all blocks and containing IDs as needed.

<Ditto
frameId="frame_601cc35d5be42cc3f6f8ad17"
>
{( frame ) => {
return Object.keys(frame.blocks).map((blockId) => (
<div className={style.footerCol} key={blockId}>
{
Object.keys(frame.blocks[blockId]).map((textId) => (
<div className={style.link} key={textId}>
{frame.blocks[blockId][textId]}
</div>
))
}
</div>
));
}}
</Ditto>

Example: Filtering by Tags

If you want to filter the text fetched by properties contained in the project itself, you can specify parameters to the filter prop of the Ditto component. This currently only supports the Tags field in Ditto, but will be expanded in the future to filter on any other metadata properties.

// will only return text with the "TOP_NAV" tag
<Ditto
frameId="frame_601cc35d5be42cc3f6f8ad15"
blockId="navigation"
filters={{ tags: ["TOP_NAV"]}}
>
{( block ) => {
return Object.keys(block).map((id) => (
<div className={style.link} key={block[id]}>{block[id]}</div>
));
}}
</Ditto>

Source

The React provider takes structured JSON outputs from Ditto projects as the source. These can be linked and automatically updated via our API/CLI, or exported manually via our web-app.

If you're using manual exports from our web-app, turn on Developer Mode in the toolbar of project you're working from to generate IDs. Then, export your file formatted with the IDs into your local directory .