<Plural>

Overview

We use the <Plural> component for handling conjugating sentences. Think of the difference between the sentences: "You have one item." and "You have two items."

In English, you have to define two different sentences based on the number of items. In other languages, you have to define up to six.

const count = 1;
<Plural n={count}
  singular={You have one item.}
  plural={You have some items.}
/>

Reference

Props

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

Description

Returns

JSX.Element containing the content corresponding to the plural form of n, or the fallback content.

Throws

Error if n is not provided or is not a valid number.

Which forms should I add?

You only need to use the plural forms in your language.

The possible forms are: "singular", "plural", "dual", "zero", "one", "two", "few", "many", "other".

• If you are a developer using "en-US", only use two: "singular" and "plural".
• If you are a developer in "zh-CN", only use "other".

Read more about the different forms here.

Examples

Basic usage

Use the <Plural> component to handle pluralization.

import { Plural } from 'gt-next';
 
export default function ItemCount({ count }) {
  return (
    <Plural n={count} 
      singular={You have one item.}
      plural={You have some items.}
    />
  );
}

Fallbacks

You can provide a fallback in case the value passed to n has no matching branches.

import { Plural } from 'gt-next';
 
export default function ItemCount({ count }) {
  return (
    <Plural n={count}
      singular={You have one item.}
    >
      You have some items.
    </Plural>
  );
}

Translating plurals

All you have to do to translate, is add the <T> component.

import { T, Plural } from 'gt-next';
 
export default function ItemCount({ count }) {
  return (
  <T id="itemCount">
    <Plural n={count}
      singular={You have an item.} 
      plural={You have some items.} 
    />
  );
}

Adding variables

What if we want to add some variables to the pluralized sentence?

import { T, Plural, Num } from 'gt-next';
 
export default function ItemCount({ count }) {
  return (
    <Plural n={count}
      singular={You have <Num>{count}</Num> item.} 
      plural={You have <Num>{count}</Num> items.} 
    />
  );
}

When inside of a <T> component, wrap all dynamic content with a <Currency>, <DateTime>, <Num>, or <Var>.

<T id="itemCount">
  <Plural n={count}
    singular={You have <Num>{count}</Num> item.} 
    plural={You have <Num>{count}</Num> items.} 
  />
</T>

Dictionary examples

The <Plural> component can also be used in a dictionary entry.

Basic usage

import { Plural } from 'gt-next';
 
const dictionary = {
  itemCount: <>
    <Plural n={1} 
      singular={You have an item.}
      plural={You have items.}
    />
  </>
}

import { useGT } from 'gt-next';
 
export default function ItemCount() {
  const t = useGT();
  return (
    <>{t('itemCount')}</>
  );
}

Passing values to dictionary entries

If you want to pass values to the dictionary entry, you must specify a name for the <Plural> component and reference it when calling the t() function.

We have also used the <Num> component and given it the same name as the <Plural> component. This way the same value will be passed to both the <Plural> and <Num> components.

import { Plural } from 'gt-next';
 
const dictionary = {
  itemCount: <>
    <Plural name='count'
      singular={You have <Num name='count'/> item.} 
      plural={You have <Num name='count'/> items.} 
    />
  </>
}

import { useGT } from 'gt-next';
 
export default function ItemCount({ count }) {
  const t = useGT();
  return (
    <>{t('itemCount', { count: 1 })}</> 
  );
}

Notes

• The <Plural> component is used to handle pluralization.
• The available plural branches (e.g., one, other, few, many) depend on the locale and follow Unicode CLDR pluralization rules.

Next steps

• For more examples, check out the reference doc on branching components here.
• For more advanced usage, combine <Plural> with variable components like <Currency>, <DateTime>, <Num>, and <Var>. Read more about variable components here.

For a deeper dive into pluralization and branching, visit Using Branching Components.