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 = { 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'), }, DatePicker: { accessibilityDismissButtonLabel: myI18nTranslator('Dismiss date picker'), dismissButton: myI18nTranslator('Close'), openCalendar: myI18nTranslator('Open calendar'), previousMonth: myI18nTranslator('Navigate to previou month'), nextMonth: myI18nTranslator('Navigate to next month'), }, 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'), accessibilityDownloadLabel: myI18nTranslator('Downloads a file'), }, 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 message'), 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:
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 message | |
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 |