Design Angular Kit

Design Angular Kit is a toolkit based on Bootstrap Italia
for the creation of web applications developed with Angular.

italia.github.io/design-angular-kit

Read this in other languages: Italiano 🇮🇹.

⚠️ If you need the old version, the code and its documentation can be found here.

Comments and contributions from the entire community are more than welcome! 🎉

Intro

Design Angular kit is a set of Angular components that implements Bootstrap Italia and the styles found in Design UI Kit. The public version of the library's documentation is available here for the latest published stable release, and here for the development version for the main branch. To play with the library, the Playground Angular Kit is available.

Index

How to use the kit
How-to-contribute
How-to-contribute-with-code
Useful links

How to use the kit

Design Angular Kit is available on NPM, to install on an existing application on which to test the library run command

npm install design-angular-kit --save

Choose the version corresponding to your Angular version:

Angular	design-angular-kit
18+	v1.1.0 +
17+	v1.0.0 +

Alternatively, you can run the command

ng add design-angular-kit --project <projectName>

He will consecutively perform:

choose the correct Angular version
install the dep
add the dep to package.json
application configuration

The instruction of the next chapter, Configuration, will be executed automatically, except for the customization of _i18n.

Configuration

App configuration

The design-angular-kit library can be used with the standalone components or with the application using the modules. Follow the configuration that corresponds to your application.

Standalone application

Use the provideDesignAngularKit function in the application configuration ApplicationConfig to initialise the library's functionality.

import { provideDesignAngularKit } from 'design-angular-kit';

export const appConfig: ApplicationConfig = {
  providers: [...provideDesignAngularKit()],
};

Modular application

You need to import DesignAngularKitModule into the main application module (usually named AppModule) using the forRoot method in order to initialise the library functionality and import all components.

import { DesignAngularKitModule } from 'design-angular-kit';

@NgModule({
  imports: [...DesignAngularKitModule.forRoot()],
})
export class AppModule {}

Uses the forChild method when importing the DesignAngularKitModule into other modules of the application to import all library components.

import { DesignAngularKitModule } from 'design-angular-kit';

@NgModule({
  imports: [...DesignAngularKitModule.forChild()],
  exports: [DesignAngularKitModule],
})
export class SharedModule {}

Hybrid application

If you have the AppModule in your application but want to use our components with the standalone configuration, use the provideDesignAngularKit function within the main application module to initialise the library functionality.

import { provideDesignAngularKit } from 'design-angular-kit';

@NgModule({
  imports: [],
  providers: [provideDesignAngularKit()],
})
export class AppModule {}

Configuration Parameters

For both the provideDesignAngularKit function and the DesignAngularKitModule.forRoot() module, an initial configuration can be used DesignAngularKitConfig.

import { provideDesignAngularKit, DesignAngularKitModule, DesignAngularKitConfig } from 'design-angular-kit';

// You can add an initial configuration to the library
const initConfig: DesignAngularKitConfig | undefined = {
  /**
   * The bootstrap-italia asset folder path
   * @default ./bootstrap-italia
   */
  assetBasePath: string | undefined,

  /**
   * Load the <a href="https://italia.github.io/bootstrap-italia/docs/come-iniziare/introduzione/#fonts">bootstrap-italia fonts</a>
   * @default true
   */
  loadFont: boolean | undefined,

  ...
};

provideDesignAngularKit(initConfig)

DesignAngularKitModule.forRoot(initConfig)

Importing bootstrap styles

Configure the required styles in the file styles.scss. Import the SCSS library as shown in the example below.

// Importing bootstrap-italia SCSS library
@import 'bootstrap-italia/src/scss/bootstrap-italia';

How to customise and override the library's default variables (e.g. colours, font-family, sizes, etc.)

.

Bootstrap Italia inherits and extends all the Bootstrap default variables, overriding some values at compile time and setting new ones when needed. One example among many is the value of the colour $primary, which in Bootstrap Italia is represented by the blue colour #0066CC, typical of the library.

The use of blue #0066CC should, however, be reserved for the central administrations of the State, and thus one may find oneself in the position of having to customise the values of the variables colour of Bootstrap Italy, setting new values for their own needs.

This colour and the other tones are generated from the HSB triad, so the variables primary-h, primary-s and primary-b must be modified. To obtain the correspondence between the hexadecimal value of the colour and HSB, one can use the rgb.to portal, e.g. https://rgb.to/0066CC.

Below is an example of a styles.scss file with colour customisation. Variable customisations must always be made before importing the bootstrap-italia.scss file.

// complete modification of the template: it is possible to recompile the library by modifying some SCSS variables

// For the override of the colour $primary of the HSB palette (colour #FF3333 https://rgb.to/ff3333):
$primary-h: 0;
$primary-s: 80;
$primary-b: 100;

// For the character family override
$font-family-serif: 'Custom Font', Georgia, serif;
$font-family-sans-serif: 'Custom Font', Arial, Helvetica, sans-serif;
$font-family-monospace: 'Custom Font', 'Courier New', Courier, monospace;

// Importing bootstrap-italia SCSS library
@import 'bootstrap-italia/src/scss/bootstrap-italia';

Icon and asset support

To add icon/asset support, edit your angular.json by adding:

{
 "assets": [
    ...
    {
      "glob": "**/*",
      "input": "./node_modules/bootstrap-italia/",
      "output": "/bootstrap-italia/"
    }
  ]
}

i18n support (localisation)

The library uses ngx-translate to add i18n localisations.

Edit your angular.json by adding:

{
  "assets": [
    ...
    {
      "glob": "**/*",
      "input": "./node_modules/design-angular-kit/assets/i18n",
      "output": "/bootstrap-italia/i18n/"
    }
  ]
}

You can use the localised labels of the design-angular-kit library in your application, e.g. {{'en.errors.required-field' | translate}}. See our labels

Existing location

If you already use localisation files in your app, you can use the library ngx-translate-multi-http-loader to load both the app's localisation files and those of the design-angular-kit library

Using the provideDesignAngularKit function:

import { HttpBackend } from '@angular/common/http';
import { TranslateLoader } from '@ngx-translate/core';
import { MultiTranslateHttpLoader } from 'ngx-translate-multi-http-loader';
import { provideDesignAngularKit } from 'design-angular-kit';

provideDesignAngularKit({
  translateLoader: (itPrefix: string, itSuffix: string) => ({
    provide: TranslateLoader,
    useFactory: (http: HttpBackend) =>
      new MultiTranslateHttpLoader(http, [
        { prefix: itPrefix, suffix: itSuffix }, // Load library translations first, so you can edit the keys in your localization file
        { prefix: './assets/i18n/' }, // Your i18n location
      ]),
    deps: [HttpBackend],
  }),
});

Using the DesignAngularKitModule:

import { HttpBackend } from '@angular/common/http';
import { TranslateLoader } from '@ngx-translate/core';
import { MultiTranslateHttpLoader } from 'ngx-translate-multi-http-loader';
import { DesignAngularKitModule } from 'design-angular-kit';

DesignAngularKitModule.forRoot({
  translateLoader: (itPrefix: string, itSuffix: string) => ({
    provide: TranslateLoader,
    useFactory: (http: HttpBackend) =>
      new MultiTranslateHttpLoader(http, [
        { prefix: itPrefix, suffix: itSuffix }, // Load library translations first, so you can edit the keys in your localization file
        { prefix: './assets/i18n/' }, // Your i18n location
      ]),
    deps: [HttpBackend],
  }),
});

Localisation customisation

If you want to customise our labels:

Do not include i18n support in your angular.json.
- Create your custom location files in your assets/bootstrap-italia/i18n/ folder (create the path if it does not exist)
- The json must have this format.
- Add the custom translateLoader in the initial library configuration, replacing the string assets/bootstrap-italia/i18n/ in the itPrefix attribute
Or, add the localisations in your json files by overwriting the library json keys.

Use

Using the DesignAngularKitModule all components of the library will be imported into the application.

Alternatively, as all our components and directives are standalone, you can import only the components/modules you need, e.g. Alerts, Pagination and Breadcrumbs.

import { ItAlertComponent, ItPaginationComponent, ItBreadcrumbsModule } from 'design-angular-kit';

@NgModule({
  imports: [
    ItAlertComponent,
    ItPaginationComponent,
    ItBreadcrumbsModule, // Includes ItBreadcrumbComponent and ItBreadcrumbItemComponent
  ],
})
export class YourAppModule {}

import { ItAlertComponent, ItPaginationComponent, ItBreadcrumbsModule } from 'design-angular-kit';

@Component({
  selector: 'app-product',
  standalone: true,
  imports: [ItAlertComponent, ItPaginationComponent, ItBreadcrumbsModule],
  templateUrl: './product.component.html',
})
export class ProductComponent {}

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 Angular Kit (a comment on the issue is also sufficient to notify the willingness to take charge).
By reporting bugs or improvements to the official repository of Angular Kit.
By writing to us on Slack's dedicated channel.

How to contribute the code

Would you like to help out on Design Angular Kit? You are in the right place!

If you haven't already done so, start by spending a few minutes to learn more about the design guidelines for PA web services, and refer to directions on how to contribute to Design Angular Kit.

Setting the local environment

The minimum requirements of your local environment must be:

NodeJS (>= 20)

At this point, you need to set up your local environment for compiling source files and generating of the documentation:

Cloning the project

git clone https://github.com/italia/design-angular-kit.git

In the project folder, install the dependencies

npm i

Launch the application locally

npm run start

To perform unit tests, run the command

npm run test

Setting up the local environment with Devcontainer

The minimum requirements of your local environment for working with Devcontainers must be:

Visual Studio Code
Docker
git

Start Visual Studio Code and install Microsoft's Dev Containers extension (ms-vscode-remote.remote-containers).

At this point, the following steps must be set up:

Cloning the project

git clone https://github.com/italia/design-angular-kit.git

Open the project folder with Visual Studio Code
Upon loading, Visual Studio Code will recognise the presentation of a devcontainer configuration. Open the project with the devcontainer. More info here.
Visual Studio Code will perform the container setup, installing the correct version of NodeJs, npm and the IDE extensions. The project dependencies will be installed in the container creation process. The development environment will be ready once the setup is complete.
Launch the application locally

npm run start

To perform unit tests, run the command

npm run test

Useful links

Playground Angular Kit
Vercel preview (updated with each commit)

From the community

Video Commit University: Developing an Angular Web App for PA from scratch (slides)
Video Meetup Angular Roma: Angular, Bootstrap Italia and more..

Contributor to the library

Special thanks to those who made the development of this library possible!


Antonino Bonanno	Cristian Borelli	Alessio Napolitano

and thanks to NetService team:

All contributors (made with contributors-img)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.EN.md

README.EN.md

Design Angular Kit

Intro

Index

How to use the kit

Configuration

App configuration

Standalone application

Modular application

Hybrid application

Configuration Parameters

Importing bootstrap styles

Icon and asset support

i18n support (localisation)

Existing location

Localisation customisation

Use

How to contribute 💙

How to contribute the code

Setting the local environment

Setting up the local environment with Devcontainer

Useful links

From the community

Contributor to the library

Files

README.EN.md

Latest commit

History

README.EN.md

File metadata and controls

Design Angular Kit

Intro

Index

How to use the kit

Configuration

App configuration

Standalone application

Modular application

Hybrid application

Configuration Parameters

Importing bootstrap styles

Icon and asset support

i18n support (localisation)

Existing location

Localisation customisation

Use

How to contribute 💙

How to contribute the code

Setting the local environment

Setting up the local environment with Devcontainer

Useful links

From the community

Contributor to the library