Get Started

Welcome to Elemental, a suite of Angular libraries designed to help you build consistent and high-quality user interfaces.

Packages

Elemental consists of the following packages:

@elemental/ui

The @elemental/ui library provides a comprehensive set of reusable UI components for building consistent and customizable user interfaces in Angular applications.

@elemental/common

The @elemental/common library offers a set of utilities and helper functions to streamline the development of Angular applications.

@elemental/media-player

The @elemental/media-player library provides components and utilities for embedding and controlling media playback in Angular applications.

@elemental/icons

The @elemental/icons library offers a comprehensive set of scalable vector icons for use in Angular applications, ensuring consistency and ease of customization.

@elemental/illustrations

The @elemental/illustrations library provides a collection of high-quality, customizable illustrations for enhancing the visual appeal of Angular applications.

Prerequisites

In order to download the Elemental packages from its private registry, add the following lines to your global .npmrc

@elemental:registry=https://gitlab.com/api/v4/projects/62690226/packages/npm/
//gitlab.com/api/v4/projects/62690226/packages/npm/:_authToken=YOUR_GITLAB_ACCESS_TOKEN

if you are using pnpm, you have also to add the following line to your global .npmrc

//gitlab.com/api/v4/projects/62690226/:_authToken=YOUR_GITLAB_ACCESS_TOKEN

Installation

To install the Elemental libraries, run the following command:

npm install @elemental/ui @elemental/common @elemental/media-player @elemental/icons @elemental/illustrations

and add to your angular.json the following options:

"options": {
  "styles": {
    "node_modules/@elemental/ui/styles/ui-mixins.scss",
    "node_modules/@elemental/ui/styles/ui-style.css",
  },
  "allowedCommonJsDependencies": ["dayjs", "bowser"],
  "stylePreprocessorOptions": {
    "includePaths": ["./node_modules"]
  }
}

Font

Elemental uses the open sans and noto sans mono fonts. You can use the following packages to include them in your application:

npm install @fontsource/noto-sans-mono @fontsource/open-sans

in your angular.json add the following options:

"options": {
  "styles": {
    "node_modules/@fontsource/open-sans/300.css",
    "node_modules/@fontsource/open-sans/300-italic.css",
    "node_modules/@fontsource/open-sans/400.css",
    "node_modules/@fontsource/open-sans/400-italic.css",
    "node_modules/@fontsource/open-sans/500.css",
    "node_modules/@fontsource/open-sans/500-italic.css",
    "node_modules/@fontsource/open-sans/600.css",
    "node_modules/@fontsource/open-sans/600-italic.css",
    "node_modules/@fontsource/open-sans/700.css",
    "node_modules/@fontsource/open-sans/700-italic.css",
    "node_modules/@fontsource/open-sans/800.css",
    "node_modules/@fontsource/open-sans/800-italic.css",
    "node_modules/@fontsource/noto-sans-mono/100.css",
    "node_modules/@fontsource/noto-sans-mono/200.css",
    "node_modules/@fontsource/noto-sans-mono/300.css",
    "node_modules/@fontsource/noto-sans-mono/400.css",
    "node_modules/@fontsource/noto-sans-mono/500.css",
    "node_modules/@fontsource/noto-sans-mono/600.css",
    "node_modules/@fontsource/noto-sans-mono/700.css",
    "node_modules/@fontsource/noto-sans-mono/800.css",
    "node_modules/@fontsource/noto-sans-mono/900.css",
  }
}

Note: This is our suggested method. You can use any other methods to include the fonts in your application.

Browser Reset

Elemental provides a browser reset that you can use to normalize the styles across different browsers. The applied styles are:

/* include some default browser css reset */
@include meta.load-css('browser-resets');

:root {
  color-scheme: light dark;
}

*,
*::before,
*::after {
  box-sizing: border-box;
}

html,
body {
  margin: 0;
  padding: 0;
  @extend .lmn-typography-body-comfortable !optional;
  color: var(--lmn-global-typography-color-neutral-primary);
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

It can be imported in your project for your entire application including the css file in the angular.json file:

"options": {
  "styles": {
    ...
    "node_modules/@elemental/ui/styles/ui-reset.css",
    ...
  },
}

Otherwhise. if you want use only for some part of your application, use the @include ui-mixins.lmn-reset; mixin in your SCSS file. For example:

@use '@elemental/ui/styles/ui-mixins';

.element {
  @include ui-mixins.lmn-reset;
}

this will apply the reset styles only to the .element class. The equivalent result will be:

.element {
  /* include some default browser css reset */
  @include meta.load-css('browser-resets');

  *,
  *::before,
  *::after {
    box-sizing: border-box;
  }

  & {
    @extend .lmn-typography-body-comfortable !optional;
    color: var(--lmn-global-typography-color-neutral-primary);
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
  }
}

Using Icons

In order to load the predefined icons, you need to load them in your application. Elemental provides a set of icons via CDN, and exposes both the CDN url and icons as individual imports.

You can use the provideIconSetFetcher method in your application main providers to load the icons from the CDN.

import { provideIconSetFetcher } from '@elemental/ui';
import { LMN_ICONS_FILLED_400_CDN_URL, LMN_ICONS_OUTLINED_400_CDN_URL } from '@elemental/icons/cdn';

export const documentationConfig: ApplicationConfig = {
  providers: [
    provideZoneChangeDetection({ eventCoalescing: true }),
    provideRouter(routes),
    provideClientHydration(),
    provideAnimations(),
    provideIconSetFetcher(LMN_ICONS_FILLED_400_CDN_URL, 'eager'),
    provideIconSetFetcher(LMN_ICONS_OUTLINED_400_CDN_URL, 'eager'),
  ],
};

check the Icons documentation for more information.

Using Illustrations

In order to load the predefined illustrations, you need to load them in your application. Elemental provides a set of illustrations via CDN, and exposes both the CDN url and illustrations as individual imports.

You can use the provideIllustrationSetFetcher method in your application main providers to load the illustrations from the CDN.

import { provideIllustrationsSetFetcher } from '@elemental/ui';
import { LMN_ILLUSTRATIONS_CDN_URL } from '@elemental/illustrations/cdn';

export const documentationConfig: ApplicationConfig = {
  providers: [
    provideZoneChangeDetection({ eventCoalescing: true }),
    provideRouter(routes),
    provideClientHydration(),
    provideAnimations(),
    provideIllustrationsSetFetcher(LMN_ILLUSTRATIONS_CDN_URL, 'eager'),
  ],
};

check the Illustrations documentation for more information.

Additional Resources

Check out the following resources to learn more about Elemental.

Guides: Learn how to use Elemental to build amazing Angular applications.
API Reference: Explore the API documentation for Elemental's libraries.