Quick start

Hive UI-Kit is a comprehensive design system created to build advanced user interfaces for Sinch SMB products.

Before start

Create a basic React app using the Typescript template and install the Hive UI-Kit library.

npx create-react-app test-app --template typescript
cd test-app
npm i @sinchsmb/ui-kit

Install required dependencies

• npm i date-fns — date utility library
• npm i formik — form library
• npm i i18next react-i18next — internationalization framework

HiveUIStarter

It is a starter wrapper around the HiveUI with a pre-configured theme, translation, localization, and pre-defined linkComponent. It is designed as an introduction to the HiveUI system and can't be configured.

Feel free to use it as a playground to better understand the system or for simple projects. Avoid using it in complex production as it can't be customized.

Example

import { HiveUIStarter } from '@sinchsmb/ui-kit/HiveUIStarter';
import { Button } from '@sinchsmb/ui-kit';

<HiveUIStarter>
  <Button>Start</Button>
</HiveUIStarter>

Custom theme, links, translation and locales

To unleash the full power of the Hive UI-Kit library, we will need to replace the <HiveUIStarter> wrapper with a more advanced <HiveUI>. But before doing that we should do some preparations.

Generate required theme

Hive Design Tokens repository contains design constants for all the available themes. Follow the steps from its readme to generate required ones. Then put the final theme files somewhere in your src folder.

Links

Hive UI is router agnostic. You can use any router library. But in some cases, Hive UI creates links. To create them based on router-specific links, you should configure the HiveUI component by passing the linkComponent prop. You can use the react-router Link component or a custom if you want.

Example

import { Link } from 'react-router-dom';

<HiveUI linkComponent={Link} {...otherProps}>{/* UI code */}</HiveUI>

Example

import { HiveUI, LinkComponent, LinkComponentProps } from '@sinchsmb/ui-kit'

const Link: LinkComponent = forwardRef<HTMLAnchorElement, LinkComponentProps>(({ to, children, ...rest }, ref) => {
  return (<a href={to} ref={ref} {...rest}>{children}</a>);
});

<HiveUI linkComponent={Link} {...otherProps}>{/* UI code */}</HiveUI>

Prepare translations and locales

Firstly, you need to prepare your translations.

You can use external services, such as Ditto, Lokalise, or Locize, to sync all your translations. Alternatively you can store your translations in files using i18next documentation format. Let's go with the second option for now.

Let's say our application supports the locales:

• English (US)
• French (Canada)

Configure language files in a similar manner:

Example

// src/language/fr/index.ts
import translation from './translation.json';
export const fr = translation;

// src/language/fr/translation.json
{
  "general": {
    "loading": "Chargement ...",
    "greeting": "Bonjour"
  },
  "forms": {
    "login": "Connexion",
    "password": "Mot de passe",
    "account": "Compte",
    "save": "Save",
    "cancel": "Annuler",
    "signin": "S'identifier"
  }
}

Do the same for English as well. Or, if built-in English translation is suitable, you can import it; see the example below

Update the App.tsx first

As almost everything is ready, it's time to update the App.tsx in the following way:

import { useMemo } from 'react';
import { HiveUI, LanguageConfig, Button, ButtonAppearance, FormikTextField } from '@sinchsmb/ui-kit';
import { createInstance } from 'i18next';
import { I18nextProvider, useTranslation } from 'react-i18next';
import { BrowserRouter, Link } from 'react-router-dom';
import { Form, Formik } from 'formik';

import { en } from '@sinchsmb/ui-kit/locale'; // use built-in English translation
import { fr } from './fr';

import theme from './messageMediaTheme.json';

import en_US from 'date-fns/locale/en-US';
import fr_CA from 'date-fns/locale/fr-CA';

function App() {
  const i18n = useMemo(() => {
    const instance = createInstance();

    instance.init({
      resources: {
        // All the used translations
        en: {
          translation: en
        },
        fr: {
          translation: fr
        },
      },
      lng: 'en',
      fallbackLng: 'en',
      interpolation: {
        escapeValue: false, // React is already protected from XSS => https://www.i18next.com/translation-function/interpolation#unescape
      },
    });

    return instance;
  }, []);

  const languages = useMemo(
    () =>
      [
        {
          language: 'en',
          defaultLocale: 'en_US',
          locales: {
            en_US: {
              dateFns: en_US,
            },
          },
        },
        {
          language: 'fr',
          defaultLocale: 'fr_CA',
          locales: {
            fr_CA: {
              dateFns: fr_CA,
            },
          },
        },
      ] as LanguageConfig[],
    [],
  );

  return (
    <BrowserRouter>
      <HiveUI i18n={i18n} theme={theme} languages={languages} linkComponent={Link}>
        <LoginUI />
      </HiveUI>
    </BrowserRouter>
  );
}

export default App;

Create new UI for <LoginUI /> component

As a final touch let's add the following code to the App.tsx file,

function LoginUI() {
  const { t } = useTranslation();

  return (
    <Formik initialValues={{}} onSubmit={() => {}}>
      <Form>
        <FormikTextField label={t('forms.login')} name="login" />
        <FormikTextField label={t('forms.password')} name="pass" obscureText />
        <Button appearance={ButtonAppearance.Primary}>{t('forms.signin')}</Button>
      </Form>
    </Formik>
  );
}

Conclusion

Now you have working UI that supports translation and visual themes. You can find more components and examples in Hive Storybook.