Skip to content
Stringtale

React

React

Stringtale is fully compatible with React as long as you’re using a back-end server to handle the communication with Stringtale. Currently we support Next.js (both the App router and the legacy Pages router) as well as Express.js as back-ends, with more coming in the future.

The implementation of Stringtale in React is very flexible. You’re not limited to just using plain text. It also supports string interpolation, formatting as well as custom components.

For all usages Stringtale uses FormatJS under the hood. So if you’re unsure about how to use it, please check out the FormatJS documentation.

Basic usage

In its most basic form Stringtale can be used anywhere you have static text that you want your clients to be able to edit. Here’s an example of how you can use Stringtale to change the text of a button.

The name attribute uniquely identifies each string. Dot-separated paths (for example based on file location) are a common convention, especially in monorepos, but any stable unique string works.

import { Value } from "@stringtale/react";


<button>
  <Value name="apps.web.src.index.header.try_now">
    Try now
  </Value>
</button>

The resulting output would be:

[Try now]

String interpolation

Stringtale isn’t limited to plain text. It also supports string interpolation.

import { Value } from "@stringtale/react";


const groceries = ["Bananas", "Pineapple", "Kiwi"]


<span>
  <Value
    name="apps.web.src.groceries.items"
    format={{
      count: groceries.length
    }}
  >
    {`Your grocery list contains {count} items.`}
  </Value>
</span>

The resulting output would be:

Your grocery list contains 3 items.

Using inline components

It’s also possible to use inline components in your strings. This can be useful when you want to use your own React components or links inside your strings. Tag names in the message must match keys in the format object.

import { Value } from "@stringtale/react";
import Link from "next/link"


<Value
  name="apps.web.src.storebanner.description"
  format={{
    bold: (c) => <strong>{c}</strong>,
    link: (c) => <Link href="/store">{c}</Link>
  }}
>
  {`For our <bold>merchandise</bold> check out the <link>store</link>.`}
</Value>

The resulting output would be:

For our merchandise check out the store.

String interpolation and text formatting combined

String interpolation and text formatting combined can be used to create more complex strings.

import { Value } from "@stringtale/react";


const hits = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
<Value
  name="apps.web.src.counter.items"
  format={{
    bold: (c) => <strong>{c}</strong>,
    count: hits.length
  }}
>
  {`Result: <bold>{count} items</bold>.`}
</Value>

Result 9 items.

Using standard HTML tags

To simplify the formatting of your strings, we’ve included an easy way to import standard HTML tags for you to use. Their usage is slightly different depending on whether it’s a self-closing tag such as <br> or not such as <b></b>.

import { Value, htmlEmptyTags, htmlFormatTags } from "@stringtale/react";


<Value
  name="apps.web.src.counter.items"
  format={{
    ...htmlEmptyTags,
    ...htmlFormatTags,
  }}
>
  {`This is a sentence with <b>bold</b>, <i>italic</i> and <u>underlined</u>
  text. It also has a linebreak {br} in the middle.`}
</Value>

The resulting output would be:

This is a sentence with bold, italic and underlined text. It also has a linebreak
in the middle.

Advanced usage

Editable text outside JSX

Most editable copy lives in JSX via <Value>. Sometimes you send text to the client as data instead. An example of this would be an error or success message from a server. You can still make that copy editable by wrapping it with toValueObject. Editors can then change it in Stringtale the same way they would a normal <Value> tag.

import { toValueObject } from "@stringtale/react"
// Alternatively: import { toValueObject } from "@stringtale/node"


export default function getPage({ result }) {
  return result.status === "ERROR"
      ? toValueObject({ name: "example.error", value: /* HTML */ `Something went wrong. Please try again later.` })
      : toValueObject({ name: "example.success", value: /* HTML */ `Your changes were saved successfully.` })
}

Next steps