@commercetools-uikit/localized-text-input

A controlled text input component for localized single-line strings with validation states.

Usage no npm install needed!

<script type="module">
  import commercetoolsUikitLocalizedTextInput from 'https://cdn.skypack.dev/@commercetools-uikit/localized-text-input';
</script>

README

LocalizedTextInput

Description

A controlled text input component for localized single-line strings with validation states.

Installation

yarn add @commercetools-uikit/localized-text-input
npm --save install @commercetools-uikit/localized-text-input

Additionally install the peer dependencies (if not present)

yarn add react react-intl
npm --save install react react-intl

Usage

import LocalizedTextInput from '@commercetools-uikit/localized-text-input';

const Example = () => (
  <LocalizedTextInput
    value={{ en: 'House', de: 'House' }}
    onChange={
      (/** event */) => {
        // alert(event.target.name, event.target.value)
      }
    }
  />
);

export default Example;

Properties

Props Type Required Default Description
id string
name string
autoComplete string
value Record then input doesn't accept a "languages" prop, instead all possible languages have to exist (with empty or filled strings) on the value: { en: 'foo', de: '', es: '' }
onChange ChangeEventHandler Gets called when any input is changed. Is called with the change event of the changed input.
selectedLanguage string Specifies which language will be shown in case the LocalizedTextInput is collapsed.
onBlur FocusEventHandler Called when any field is blurred. Is called with the event of that field.
onFocus FocusEventHandler Called when any field is focussed. Is called with the event of that field.
hideLanguageExpansionControls boolean Will hide the language expansion controls when set to true. All languages will be shown when set to true.
defaultExpandLanguages boolean Controls whether one or all languages are visible by default
isAutofocussed boolean Focus the input field on initial render
isDisabled boolean Disables all input fields.
isReadOnly boolean Disables all input fields and shows them in read-only mode.
placeholder Record Placeholders for each language. Object of the same shape as value.
horizontalConstraint union
Possible values:
, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 'scale', 'auto'
'scale' Horizontal size limit of the input fields.
hasError boolean Will apply the error state to each input without showing any error message.
errors Record Used to show errors underneath the inputs of specific currencies. Pass an object whose key is a currency and whose value is the error to show for that key.

data-* props

The component forwards all data attribute props. It further adds a -${language} suffix to the values of the data-test and data-track-component attributes, e.g data-test="foo" will get added to the input for en as data-test="foo-en".

Main Functions and use cases are:

  • Receiving localized input from user

Static Properties

createLocalizedString(languages, existingTranslations)

This function creates a localized string. It merges the languages and the language keys of existing translations to form a localized string holding all languages. The existingTranslations argument is optional. If it is not passed, an empty localized field will be created.

const languages = ['en', 'de'];
LocalizedTextInput.createLocalizedString(languages);
// -> { en: '', de: '' }

In case existingTranslations is passed, it will merge an empty localized field with the exisiting translations. Usually this is used to ensure that a localized string contains at least the project's languages.

const languages = ['en', 'de'];
const existingTranslations = { en: 'Tree', ar: 'شجرة' };
LocalizedTextInput.createLocalizedString(languages, existingTranslations);
// -> { en: 'Tree', de: '', ar: 'شجرة' }

isEmpty(localizedField)

Returns true when all values in a localized field are empty.

LocalizedTextInput.isEmpty({});
// -> true
LocalizedTextInput.isEmpty({ en: '', de: '  ' });
// -> true
LocalizedTextInput.isEmpty({ en: 'Tree', de: '' });
// -> false

omitEmptyTranslations(localizedField)

Omits translations with empty values.

LocalizedTextInput.omitEmptyTranslations({ en: '', de: '  ' });
// -> {}
LocalizedTextInput.omitEmptyTranslations({ en: 'Tree', de: '' });
// -> { en: 'Tree' }

isTouched(touched)

Expects to be called with an object or undefined. Returns true when at least one value is truthy.

RequiredValueErrorMessage

This field exports a default error message which can be used when the field is required, but the user provided no value. You can use it as

<LocalizedTextInput hasError={isMissing} />;
{
  isMissing && <LocalizedTextInput.RequiredValueErrorMessage />;
}

getId(idPrefix, language)

Returns the id of the input field of a specific language. This is useful in case you want to create a label for the input field. You can use it as

LocalizedTextInput.getId('name', 'en');
// -> "name.en"

Or as a more complete example:

<label htmlFor={LocalizedTextInput.getId('name', 'en')}>Name</label>
<LocalizedTextInput
  id="name"
  selectedLanguage="en"
  // ...
/>

getName(idPrefix, language)

Returns the name of the input field of a specific language. . You can use it as

LocalizedTextInput.getName('slug', 'en');
// -> "slug.en"