Design-react-kit NPM

Read this in other languages: Italiano 🇮🇹.

⚠️ Warning: This kit was designed to work with Bootstrap Italia version 2.x. The kit for version 1.x of Bootstrap Italia has been deprecated and is located on the 4.x branch (https://github.com/italia/design-react-kit/tree/4.x).

Intro

Design React kit is a set of React components that implements Bootstrap Italia and Design UI Kit styling. Components are showcased with Storybook. Public version of Storybook is available here for the latest stable release. To play with the library, the Playground React Kit is available.

Table of contents

Usage

To use Design React as a dependency in your React project you can install it from npm. We suggest to use create vite to create a new React webapp from scratch as follows:

yarn create vite my-react-app --template react
cd nome-app
yarn add design-react-kit --save

More information on creating a new app with React:

Add bootstrap-italia and fonts

The design-react-kit module does not include the CSS and font files in the bundle, so this needs to be installed as well:

yarn add bootstrap-italia typeface-lora typeface-roboto-mono typeface-titillium-web --save

Example

Then, you just need to import CSS e font editing ./src/App.js as shown:

import React from 'react';
import './App.css';
import { Alert } from 'design-react-kit';
import 'bootstrap-italia/dist/css/bootstrap-italia.min.css';
import 'typeface-titillium-web';
import 'typeface-roboto-mono';
import 'typeface-lora';

function App() {
  return <Alert>This is an Alert</Alert>;
}

export default App;

You can consult this web template with StackBlitz: Web template

Loading Fonts

The Bootstrap Italia theme defines a specific set of font typefaces to work: titillium-web, roboto-mono and lora. The loading of this set of fonts can be left to the browser or controlled: in this last case it is necessary to use the FontLoader component exported by the library. Declaring the FontLoader on top of the Application tree it is enough to trigger the loading of the fonts.

As alternative it is required to manually manage the loading via the webfontloader package:

const WebFont = require('webfontloader');
WebFont.load({
  custom: {
    families: ['Titillium Web:300,400,600,700:latin-ext', 'Lora:400,700:latin-ext', 'Roboto Mono:400,700:latin-ext']
  }
});

Peer dependencies

The library does not include react and react-dom, avoiding versions clashing and increasing the size of the bundle. For this reason, for local development it will be necessary to manually install dependencies.

The command to be executed is

yarn install --peers

or alternatively manually

yarn install react react-dom

How to contribute 💙

👉🏻 You can contribute to the library in various ways:

With your own code, taking charge of an issue among those open and not already assigned among the issues of React Kit (even a comment on the issue to notify the desire to take charge).
By reporting bugs or improvements to the React Kit official repository.
By writing to us on the dedicated channel of Slack.

How to contribute with your own code

The minimum requirements of your local environment should be:

NodeJS (>= 18)
Yarn

Clone the repo and run yarn to install the dependencies. Then run the yarn storybook:serve command to start the development server.

Storybook will therefore be available at http://localhost:9001/

Public version of the Storybook is available here.

Storybook has been enriched with some addons that make it more talented. Check dependencies on the package.json file for details.

How to create new components

This section explains how to create new components in the repository. All components reside in the src directory: each component is a folder with all that is needed to make it work. Storybook stories are instead under stories.
Unit tests are under the test folder.

i.e. the Button component is shown below the src/Button path and its structure is as follows:

├── src
│    └── Button
│        └── Button.tsx
├── stories
│    ├── Components
│    │   └── Button.stories.tsx
│    └── Documentation
│        └── Button.mdx
└── test
     └── Button.test.tsx

Some basic rules for structuring the components:

TSX file component files use JSX syntax.
The .stories.tsx files only contains examples relative to component.
The .mdx files only contains documentation relative to component.
The .test.tsx files only contains tests relative to component.

Once you have created a new component, with its history, starting Storybook will be able to check that everything works as it should.

Documentation:

Snapshot tests

The testing system has been provided with a snapshot check on existing stories: this means that each story content is copied into a special file used as reference to check changes in the future. This might fail some test checks on the PR in case of new or changed stories.
In such case it is possible to update the snapshot file with the following command:

yarn test -u

At this point create a new commit and update the PR. Make sure to check the new snapshot content whether it is in line with the changes made before pushing.

Building library

To build the library and add files into the dist folder:

yarn build

Useful links

Playground React Kit

Browsers support

The design kit follows the Guidelines for Public Services Design, within the Section 6.3.1.2.1. Supporto browser via the package browserslist-config-design-italia.