DefaultLabelProvider is an optional React Context provider to provide default strings for Gestalt component labels that support it. This allows for faster development by reducing boilerplate props at the callsite.

Props

Component props
Name
Type
Default
children
Required
React.Node
-
labels
null | DefaultLabelContextType
-

An object describing the default strings to be used by supported component labels throughout your app. If your app supports i18n, don't forget to translate your strings!

Note that all supported labels for all supported components must be provided if using this Provider. Omit this prop to use default (English) strings for supported labels.

See the source code for the specific shape of this object.

Implementation

To support internationalization and accessibility, Gestalt components have many required accessibility labels. This allows you to pass translated strings to ensure that users of all abilities and languages can use your app.

However, certain labels are unlikely to change based on the specific implementation, e.g. the accessibility label for the close button on a modal. For supported labels on certain components, you can specify the label once, at the top level of your app, for use in all instances of that component throughout your app. This allows for certain accessibility label props to now be optional; the default label will be used unless overridden at the callsite.

If your app supports internationalization, pass translated strings to the Provider. If your app does not support internationalization, you may pass untranslated strings, or you may omit the labels prop or pass null to use our default labels. See the source code for the default English labels we provide.

In the examples below, type a character to make the "clear input" icon button appear, then inspect that element and note the accessibility label.

import { useState } from 'react';
import { Box, ComboBox, DefaultLabelProvider, Flex, Heading } from 'gestalt';

const myI18nTranslator = (val) => val.toUpperCase();

const labels = {
  Accordion: {
    accessibilityCollapseLabel: myI18nTranslator('Collapse section'),
    accessibilityExpandLabel: myI18nTranslator('Expand section'),
  },
  ActivationCard: {
    accessibilityDismissButtonLabel: myI18nTranslator('Dismiss'),
  },
  BannerOverlay: {
    accessibilityDismissButtonLabel: myI18nTranslator('Dismiss Banner'),
  },
  BannerCallout: {
    accessibilityDismissButtonLabel: myI18nTranslator('Dismiss Banner'),
    iconAccessibilityLabelError: myI18nTranslator('Error'),
    iconAccessibilityLabelInfo: myI18nTranslator('Information'),
    iconAccessibilityLabelRecommendation: myI18nTranslator('Recommendation'),
    iconAccessibilityLabelWarning: myI18nTranslator('Warning'),
    iconAccessibilityLabelSuccess: myI18nTranslator('Success'),
  },
  DateRange: {
    cancelText: myI18nTranslator('Cancel'),
    applyText: myI18nTranslator('Apply'),
  },
  ChartGraph: {
    accessibilityLabelPrefixText: myI18nTranslator('ChartGraph'),
    defaultViewText: myI18nTranslator('Default view mode'),
    accessibleViewText: myI18nTranslator('Visual pattern view'),
    tabularData: myI18nTranslator('Tabular representation'),
    accessibilityLabelDismissModal: myI18nTranslator(
      'Dismiss tabular representation modal'
    ),
    tableSeriesText: myI18nTranslator('Series'),
    tableXAxisText: myI18nTranslator('x-axis values'),
    tableYAxisText: myI18nTranslator('y-axis values'),
    downloadCsvButtonText: myI18nTranslator('Download as .csv'),
    cancelButtonText: myI18nTranslator('Cancel'),
  },
  ComboBox: {
    noResultText: myI18nTranslator('No results'),
    accessibilityClearButtonLabel: myI18nTranslator('Clear input'),
  },
  Link: {
    accessibilityNewTabLabel: myI18nTranslator('Opens a new tab'),
  },
  Modal: {
    accessibilityDismissButtonLabel: myI18nTranslator('Dismiss modal'),
  },
  Popover: {
    accessibilityDismissButtonLabel: myI18nTranslator('Dismiss popover'),
  },
  OverlayPanel: {
    accessibilityDismissButtonLabel: myI18nTranslator('Dismiss overlay panel'),
    dismissConfirmationMessage: myI18nTranslator(
      'Are you sure you want to dismiss?'
    ),
    dismissConfirmationSubtext: myI18nTranslator(
      'You will lose all of your changes. This cannot be undone'
    ),
    dismissConfirmationPrimaryActionText: myI18nTranslator('Yes, dismiss'),
    dismissConfirmationPrimaryActionTextLabel: myI18nTranslator(
      'Yes, dismiss the overlay panel'
    ),
    dismissConfirmationSecondaryActionText: myI18nTranslator('No, go back'),
    dismissConfirmationSecondaryActionTextLabel: myI18nTranslator(
      'No, go back to the overlay panel'
    ),
  },
  SheetMobile: {
    accessibilityDismissButtonLabel: myI18nTranslator('Dismiss bottom sheet'),
    accessibilityGrabberLabel: myI18nTranslator('Grabber'),
    accessibilityLabel: myI18nTranslator('Bottom sheet'),
  },
  SideNavigation: {
    accessibilityDismissButtonLabel: myI18nTranslator(
      'Dismiss side navigation'
    ),
    accessibilityCollapseButtonLabel: myI18nTranslator(
      'Navigation expanded. Click button to collapse.'
    ),
    accessibilityExpandButtonLabel: myI18nTranslator(
      'Navigation collapsed. Click button to expand.'
    ),
    accessibilityEllipsisLabel: myI18nTranslator(
      'Collapsed navigation items. Expand for more options'
    ),
  },
  BannerSlim: {
    accessibilityDismissButtonLabel: myI18nTranslator('Dismiss banner'),
    iconAccessibilityLabelError: myI18nTranslator('Error'),
    iconAccessibilityLabelInfo: myI18nTranslator('Information'),
    iconAccessibilityLabelRecommendation: myI18nTranslator('Recommendation'),
    iconAccessibilityLabelWarning: myI18nTranslator('Warning'),
    iconAccessibilityLabelSuccess: myI18nTranslator('Success'),
  },
  Spinner: {
    accessibilityLabel: myI18nTranslator('Loading'),
  },
  TableOfContents: {
    accessibilityLabel: myI18nTranslator('Table of contents'),
  },
  Tag: {
    accessibilityErrorIconLabel: myI18nTranslator('Error'),
    accessibilityRemoveIconLabel: myI18nTranslator('Remove tag'),
    accessibilityWarningIconLabel: myI18nTranslator('Warning'),
  },
  TagData: {
    accessibilityRemoveIconLabel: myI18nTranslator('Remove tag'),
  },
  TextField: {
    accessibilityHidePasswordLabel: myI18nTranslator('Hide password'),
    accessibilityShowPasswordLabel: myI18nTranslator('Show password'),
  },
  HelpButton: {
    tooltipMessage: myI18nTranslator('Click to learn more'),
  },
  Toast: {
    accessibilityDismissButtonLabel: myI18nTranslator('Dismiss toast'),
    accessibilityIconSuccessLabel: myI18nTranslator('Success message'),
    accessibilityIconErrorLabel: myI18nTranslator('Error message'),
    accessibilityProcessingLabel: myI18nTranslator('Processing message'),
  },
  BannerUpsell: {
    accessibilityDismissButtonLabel: myI18nTranslator('Dismiss banner'),
  },
  Video: {
    accessibilityMaximizeLabel: myI18nTranslator('Maximize'),
    accessibilityMinimizeLabel: myI18nTranslator('Minimize'),
    accessibilityMuteLabel: myI18nTranslator('Mute'),
    accessibilityPauseLabel: myI18nTranslator('Pause'),
    accessibilityPlayLabel: myI18nTranslator('Play'),
    accessibilityProgressLabel: myI18nTranslator('Video progress'),
    accessibilityUnmuteLabel: myI18nTranslator('Unmute'),
    accessibilityHideCaptionsLabel: myI18nTranslator('Hide captions'),
    accessibilityShowCaptionsLabel: myI18nTranslator('Show captions'),
  },
};

const pronouns = [
  'ey / em',
  'he / him',
  'ne / nem',
  'she / her',
  'they / them',
  've / ver',
  'xe / xem',
  'xie / xem',
  'zie / zem',
];

export default function Example() {
  const [errorMessage, setErrorMessage] = useState();

  const handleOnBlur = ({ value }) => {
    if (value !== '' && !pronouns.includes(value))
      setErrorMessage('Please, select a valid option');
  };

  const resetErrorMessage = errorMessage ? () => setErrorMessage() : () => {};

  return (
    <DefaultLabelProvider labels={labels}>
      <Box height="100%" marginTop={3} padding={2} width="100%">
        <Flex
          alignItems="center"
          direction="column"
          gap={5}
          height="100%"
          justifyContent="center"
          width="100%"
        >
          <Heading size="300">For apps using internationalization</Heading>

          <Box width={320}>
            <ComboBox
              errorMessage={errorMessage}
              helperText="Choose your pronouns to appear on your profile so others know how to refer to you. You can edit or remove these any time."
              id="translations-combobox"
              label="Pronouns"
              noResultText="No results for your selection"
              onBlur={handleOnBlur}
              onChange={resetErrorMessage}
              onClear={resetErrorMessage}
              options={pronouns.map((pronoun, index) => ({
                label: pronoun,
                value: `value${index}`,
              }))}
              placeholder="Add your pronouns"
            />
          </Box>
        </Flex>
      </Box>
    </DefaultLabelProvider>
  );
}

import { useState } from 'react';
import { Box, ComboBox, DefaultLabelProvider, Flex, Heading } from 'gestalt';

const pronouns = [
  'ey / em',
  'he / him',
  'ne / nem',
  'she / her',
  'they / them',
  've / ver',
  'xe / xem',
  'xie / xem',
  'zie / zem',
];

export default function Example() {
  const [errorMessage, setErrorMessage] = useState();

  const handleOnBlur = ({ value }) => {
    if (value !== '' && !pronouns.includes(value))
      setErrorMessage('Please, select a valid option');
  };

  const resetErrorMessage = errorMessage ? () => setErrorMessage() : () => {};

  return (
    <DefaultLabelProvider>
      <Box height="100%" marginTop={3} padding={2} width="100%">
        <Flex
          alignItems="center"
          direction="column"
          gap={5}
          height="100%"
          justifyContent="center"
          width="100%"
        >
          <Heading size="300">For apps not using internationalization</Heading>

          <Box width={320}>
            <ComboBox
              errorMessage={errorMessage}
              helperText="Choose your pronouns to appear on your profile so others know how to refer to you. You can edit or remove these any time."
              id="no-translations-combobox"
              label="Pronouns"
              noResultText="No results for your selection"
              onBlur={handleOnBlur}
              onChange={resetErrorMessage}
              onClear={resetErrorMessage}
              options={pronouns.map((pronoun, index) => ({
                label: pronoun,
                value: `value${index}`,
              }))}
              placeholder="Add your pronouns"
            />
          </Box>
        </Flex>
      </Box>
    </DefaultLabelProvider>
  );
}

Default strings provided

The following strings are provided by default:

Default strings provided table
Component
Prop
Default String
accessibilityCollapseLabel
Collapse section
accessibilityExpandLabel
Expand section
accessibilityDismissButtonLabel
Dismiss
accessibilityDismissButtonLabel
Dismiss Banner
iconAccessibilityLabelError
Error
iconAccessibilityLabelInfo
Information
iconAccessibilityLabelRecommendation
Recommendation
iconAccessibilityLabelWarning
Warning
iconAccessibilityLabelSuccess
Success
accessibilityDismissButtonLabel
Dismiss banner
accessibilityLabelPrefixText
ChartGraph
defaultViewText
Default view mode
tabularData
Tabular representation
accessibilityLabelDismissModal
Dismiss tabular representation modal
tableSeriesText
Series
tableXAxisText
x-axis values
tableYAxisText
y-axis values
downloadCsvButtonText
Download as .csv
cancelButtonText
Cancel
noResultText
No results
accessibilityClearButtonLabel
Clear input
applyText
Apply
cancelText
Cancel
accessibilityNewTabLabel
Opens a new tab
accessibilityDismissButtonLabel
Dismiss modal
accessibilityDismissButtonLabel
Dismiss popover
accessibilityDismissButtonLabel
Dismiss overlay panel
dismissConfirmationMessage
Are you sure you want to dismiss?
dismissConfirmationSubtext
You will lose all of your changes. This cannot be undone
dismissConfirmationPrimaryActionText
Yes, dismiss
dismissConfirmationPrimaryActionTextLabel
Yes, dismiss the overlay panel
dismissConfirmationSecondaryActionText
No, go back
dismissConfirmationSecondaryActionTextLabel
No, go back to the overlay panel
accessibilityDismissButtonLabel
Dismiss bottom sheet
accessibilityGrabberLabel
Grabber
accessibilityLabel
Bottom sheet
accessibilityDismissButtonLabel
Dismiss side navigation
accessibilityDismissButtonLabel
Dismiss banner
iconAccessibilityLabelError
Error
iconAccessibilityLabelInfo
Information
iconAccessibilityLabelRecommendation
Recommendation
iconAccessibilityLabelWarning
Warning
iconAccessibilityLabelSuccess
Success
accessibilityLabel
Loading
accessibilityLabel
Table of contents
accessibilityErrorIconLabel
Error
accessibilityRemoveIconLabel
Remove tag
accessibilityWarningIconLabel
Warning
accessibilityRemoveIconLabel
Remove tag
accessibilityHidePasswordLabel
Hide password
accessibilityShowPasswordLabel
Show password
tooltipMessage
Click to learn more
accessibilityDismissButtonLabel
Dismiss toast
accessibilityIconSuccessLabel
Success message
accessibilityIconErrorLabel
Error message
accessibilityProcessingLabel
Processing message
accessibilityMaximizeLabel
Maximize
accessibilityMinimizeLabel
Minimize
accessibilityMuteLabel
Mute
accessibilityPauseLabel
Pause
accessibilityPlayLabel
Play
accessibilityProgressLabel
Video progress
accessibilityUnmuteLabel
Unmute
accessibilityHideCaptionsLabel
Hide captions
accessibilityShowCaptionsLabel
Show captions

Internal documentation