Branching Components

Overview

Branching Components in gt-next enable dynamic content rendering based on specific conditions. These components include:

<Branch>: Renders content based on a matching branch prop.
<Plural>: Renders content based on pluralization rules for a given number.

Both components provide powerful tools for managing conditional logic and dynamic content in localized applications.

In this reference, we will cover:

What Branching Components are and how they work.
Design patterns for using Branching Components effectively.
Some examples of how to use each Branching Component.
Common pitfalls to avoid when working with Branching Components.

What Are Branching Components?

Branching Components dynamically choose which content to render based on a specific condition or value.

`<Branch>` Component

The <Branch> component allows you to render different content based on a provided branch value. If no matching branch is found, the fallback children content is rendered.

For example, the <Branch> component is perfect for conditional rendering based on application state, user preferences, or any dynamic data.

The <Plural> component extends the functionality of <Branch> by handling pluralization and number agreement automatically. It uses the provided n value to determine which plural form to display, based on locale-specific rules.

For example, the <Plural> component is ideal for rendering singular and plural text dynamically, such as "1 item" vs. "2 items."

Design Patterns

Branching Logic with `<Branch>`

The <Branch> component is used for flexible content switching based on a branch value. You can define multiple possible branches, and the component will render the content corresponding to the matching branch key.

import { T, Branch } from 'gt-next';
 
export default function UserStatus({ status }) {
  return (
    <T id="UserStatus">
      <Branch
        branch={status}
        active={<p>The user is active.</p>}
        inactive={<p>The user is inactive.</p>}
      >
        <p>Status unknown.</p>
      </Branch>
    </T>
  );
}

Pluralization with `<Plural>`

The <Plural> component automates pluralization logic based on the value of n. The component dynamically chooses the appropriate plural form for the given number and locale.

import { T, Plural } from 'gt-next';
 
export default function ItemCount({ count }) {
  return (
    <T id="item_count">
      <Plural
        n={count}
        one={<>You have <Num>1</Num> item.</>}
        other={<>You have <Num>{count}</Num> items.</>}
      />
    </T>
  );
}

The available plural forms depend on the locale and follow Unicode CLDR pluralization rules.

Examples

`<Branch>` Example

The <Branch> component dynamically renders content based on the provided branch prop. In this example, it displays different descriptions based on the user's subscription plan.

import { Branch } from 'gt-next';
 
export default function SubscriptionDetails({ plan }) {
  return (
    <Branch
      branch={plan}
      free={<p>You are on the Free plan. Upgrade to unlock more features!</p>}
      premium={<p>You are enjoying the Premium plan with full access to features.</p>}
      enterprise={<p>You are on the Enterprise plan. Contact support for tailored solutions.</p>}
    >
      <p>No subscription plan detected.</p>
    </Branch>
  );
}

The branch prop determines which plan message to display.
If plan is "free", "premium", or "enterprise", the corresponding message is shown.
If plan doesn't match any of these values, the fallback content ("No subscription plan detected.") is displayed.

`<Plural>` Example

The <Plural> component dynamically handles singular and plural content based on the value of n. This example displays the number of unread messages in a user's inbox.

import { T, Plural, Num } from 'gt-next';
 
export default function UnreadMessages({ unreadCount }) {
  return (
    <T id="unread_messages">
      <Plural
        n={unreadCount}
        one={<>You have <Num>{unreadCount}</Num> unread message.</>}
        other={<>You have <Num>{unreadCount}</Num> unread messages.</>}
      />
    </T>
  );
}

The n prop specifies the number of unread messages.
If unreadCount is 1, it renders: "You have 1 unread message."
For any other value, it renders: "You have X unread messages." where X is the value of unreadCount formatted by <Num>.

Common Pitfalls

Missing Branch Values

If a branch value is not provided or does not match any keys, the <Branch> component will render the fallback children content. Always ensure that the possible branch keys match the values passed to the branch prop.

import { Branch } from 'gt-next';
 
export default function StatusMessage({ status }) {
  return (
    <Branch
      branch={status}
      active={<p>The user is active.</p>}
      inactive={<p>The user is inactive.</p>}
    >
      <p>Status unknown.</p>
    </Branch>
  );
}

If status is undefined or a value other than active or inactive, the fallback content “Status unknown.” will be displayed.

Missing Plural Forms

Remember to specify all necessary plural forms in your fallback language. This is how gt-next ensures that your application always has fallback content to display.

Notes

Branching Components are essential for managing dynamic and localized content in applications.
The <Branch> component is highly flexible and can adapt to various conditions and states.
The <Plural> component simplifies pluralization by adhering to locale-specific rules automatically.
Always include a fallback children prop for better error handling and user experience.

Next Steps

Check out <Branch> and <Plural> in the API Reference for more details.
Learn more about pluralization rules and branching logic in Unicode CLDR Pluralization Rules.
Explore Variable Components in our reference guide.