<Branch>

Overview

The <Branch> component allows you to add conditional logic to a translation.

const status = 'active';
<Branch branch={status}
    active={<p>The user is active.</p>}
    inactive={<p>The user is inactive.</p>}
/>

You pass a value to the branch parameter, and this gets matched with an output value based on the keys you provide.

Reference

Props

Prop	Type	Default
`branch`	`string`	-
`children?`	`any`	`undefined`
`name?`	`string`	`undefined`
`[key]: string`	`string \| JSX.Element`	-

The [key]: string syntax indicates arbitrary keys representing potential branches. For example, branches like active and inactive can be added as parameters.

Prop	Description
`branch`	The name of the branch to render.
`children`	Fallback content to render if no matching branch is found.
`name`	Optional name for the component, used for a dictionary design pattern.
`[key]: string`	Branches representing possible content for the given branch value. Each key corresponds to a branch, and its value is the content to render.

Returns

JSX.Element containing the content corresponding to the specified branch or the fallback content.

Throws

Error if the branch prop is not provided or is invalid.

Examples

Basic usage

<Branch> needs to have a different output for each possible value of the branch prop.

In this example, the user.hairColor value is used to determine the output. We have defined props black, brown, and blonde to match the possible values of user.hairColor.

BranchExample.jsx

import { Branch } from 'gt-next';
 
export default function HairColor({ user }) {
  return (
    <Branch branch={user.hairColor} 
      black={<p>Their hair is dark.</p>}
      brown="Their hair is in the middle." // (you can pass a string if you prefer)
      blonde={<p>Their hair is light.</p>}
    />
  );
}

Fallback content

The children will always be used as a fallback if no prop matches the value passed to branch.

BranchExample.jsx

import { Branch } from 'gt-next';
 
export default function HairColor({ user }) {
  return (
    <Branch branch={user.hairColor}
      black={<p>Their hair is dark.</p>}
      brown={<p>Their hair is in the middle.</p>}
      blonde={<p>Their hair is light.</p>}
    >
      <p>Their hair is unknown.</p>
    </Branch>
  );
}

Translating `<Branch>`

If you want to translate the content, simply wrap it in a <T> component.

BranchExample.jsx

import { T, Branch } from 'gt-next';
 
export default function HairColor({ user }) {
  return (
    <T id="example">
      <Branch branch={user.hairColor}
        black={<p>Their hair is dark.</p>}
        brown={<p>Their hair is in the middle.</p>}
        blonde={<p>Their hair is light.</p>}
      >
        <p>Their hair is unknown.</p> 
      </Branch>
    </T> 
  );
}

Adding variables

If you want to render dynamic values in the branch, make sure to wrap them in <Currency>, <DateTime>, <Num>, or <Var> components.

BranchExample.jsx

import { Branch, T, Var } from 'gt-next';
 
export default function HairColor({ user }) {
  return (
    <T id="example">
      <Branch branch={user.hairColor}
        black={<p>Their hair is dark.</p>}
        brown={<p>Their hair is in the middle.</p>}
        blonde={<p>Their hair is light.</p>}
      >
        <p>Unhandled hair color: <Var>{user.hairColor}</Var></p>
      </Branch>
    </T>
  );
}

Using a dictionary

Basic usage

dictionary.jsx

import { Branch } from 'gt-next';
 
const dictionary = {
  hairColor: <>
    <Branch branch="black"
      black={<>Their hair is dark.</>}
      brown={<>Their hair is in the middle.</>}
      blonde={<>Their hair is light.</>}
    />
  </>,
};

HairColor.jsx

import { useGT } from 'gt-next';
 
export default function HairColor(user) {
  const t = useGT();
  return (
    <div>
      { t('hairColor') }
    </div>
  );
}

Passing values to dictionary entries

In order to pass values, you must specify a name for the <Branch> (or other) component(s) and reference it when calling the t() function.

In this example, we see that hairColor is passed to both <Branch> and <Var> components.

dictionary.jsx

import { Branch, Var } from 'gt-next';
 
const dictionary = {
  hairColor: <>
    <Branch name="hairColor"
      black={<>Their hair is dark.</>}
      brown={<>Their hair is in the middle.</>}
      blonde={<>Their hair is light.</>}
      >
        <p>Unhandled hair color: <Var name="hairColor"/></p>
      </Branch>
  </>,
};

HairColor.jsx

import { useGT } from 'gt-next';
 
export default function HairColor(user) {
  const t = useGT();
  return (
    <div>
      { t('hairColor', { hairColor: user.hairColor }) }
    </div>
  );
}

Notes

The keys for branches can be any string value that matches the branch prop. This flexibility makes it easy to adapt <Branch> to a wide range of use cases.
Combine <Branch> with other components, such as <T> for translations and variable components for dynamic content, to create rich and localized interfaces.

Next steps

For more advanced usage and examples, refer to Using Branching Components.
To learn more about variable components like <Currency>, <DateTime>, <Num>, and <Var>, see the Using Variable Components documentation.

<Branch>

On this page