DefaultLabelProvider
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
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 = { ActivationCard: { accessibilityDismissButtonLabel: myI18nTranslator('Dismiss'), }, Callout: { 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'), }, 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' ), }, SlimBanner: { 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'), }, Upsell: { 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:
Component | Prop | Default String |
---|---|---|
accessibilityDismissButtonLabel | Dismiss | |
accessibilityDismissButtonLabel | Dismiss Banner | |
iconAccessibilityLabelError | Error | |
iconAccessibilityLabelInfo | Information | |
iconAccessibilityLabelRecommendation | Recommendation | |
iconAccessibilityLabelWarning | Warning | |
iconAccessibilityLabelSuccess | Success | |
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 | |
accessibilityDismissButtonLabel | Dismiss banner | |
accessibilityMaximizeLabel | Maximize | |
accessibilityMinimizeLabel | Minimize | |
accessibilityMuteLabel | Mute | |
accessibilityPauseLabel | Pause | |
accessibilityPlayLabel | Play | |
accessibilityProgressLabel | Video progress | |
accessibilityUnmuteLabel | Unmute | |
accessibilityHideCaptionsLabel | Hide captions | |
accessibilityShowCaptionsLabel | Show captions |