@metromobilite/m-ui
M-UI
M-UI is a component library built on top of Angular Material 15, designed to extend its capabilities while leveraging M-Theme for styling consistency. It provides:
- Ready-to-use Angular components tailored for specific use cases.
- An intuitive API for developers, enabling seamless integration.
- Theming support out-of-the-box, powered by M-Theme.
Motivation
While working on various projects, especially when building Angular applications, I noticed a common need for:
- A unified theming system that simplifies the customization of Angular Material components.
- A component library that goes beyond the basic Angular Material design system to meet specific business needs.
Other solutions often fell short:
- Writing custom themes manually was repetitive and prone to errors.
- Extending Angular Material components often required complex configurations.
- Integrating theming and custom components into a single cohesive package was challenging.
M-Theme and M-UI address these gaps:
- M-Theme simplifies theming by centralizing styles, reducing repetitive code, and offering pre-built palettes and functions.
- M-UI extends Angular Material with additional components, allowing developers to create rich, feature-complete applications faster.
How does it work?
M-Theme
- Provides SCSS files for defining light and dark themes.
- Offers pre-configured variables and helper functions to make styling Angular Material components easier.
- Works seamlessly with Angular's build process, requiring only the addition of the necessary imports in your main SCSS file.
M-ui
- Built as a library of Angular components that extend Angular Material's functionality.
- Components are designed to be modular:
- Import only the components you need or the entire library.
- All components are styled consistently using M-Theme.
- Supports standalone usage and integration into existing Angular projects.
Peer dependencies
M-UI depends on Angular Material and Angular CDK. We need to install these dependencies before installing M-UI.
| Peer Dependency | Version |
|---|---|
| @angular/common | 15.2.0 |
| @angular/cdk | 15.2.0 |
| @angular/core | 15.2.0 |
| @angular/material | 15.2.8 |
Configuration/installation
Installing the Library
- Install via npm
Run the following command to install the latest version of the library:
npm i @metromobilite/m-ui@latestConfiguration
M-Theme Setup
Step 1: Add stylePreprocessorOptions in angular.json
Note The
stylePreprocessorOptionsinangular.jsonallows you to define custom paths for Sass to search for files during@useor@import.Adding 'includePaths': ['node_modules'] lets Sass resolve imports from node_modules directly, enabling simplified imports for libraries.
{
"projects": {
"project-name": {
"architect": {
"build": {
"options": {
"stylePreprocessorOptions": {
"includePaths": ["node_modules"]
}
}
}
}
}
}
}Step 2: Add Assets in angular.json
To ensure that theme-related assets are properly loaded, include the following in the assets array of angular.json:
{
"assets": [
{
"glob": "**/*",
"input": "./node_modules/@metromobilite/m-ui/theme/assets/",
"output": "./assets/"
}
]
}Step 3: Import Styles in styles.scss
In your main SCSS file (e.g., src/styles.scss), import the M-Theme styles. You can choose to import all styles or only specific ones.
Option 1: Import All Styles
$assets-path: '/assets'; // Define the assets path
@use "@metromobilite/m-ui/theme/style";Option 2: Import Specific Files
If you need more control over the imported styles, you can import them one by one:
@import 'reset';
@import 'variables';
@import 'font';
@import '@metromobilite/m-ui/theme/theme';
@import 'classes';
@import 'components/index';M-UI Setup
Add Icon Assets in angular.json
To use the icon library provided by M-UI, include the following configuration in angular.json under the assets array:
{
"assets": [
{
"glob": "**/*",
"input": "node_modules/@metromobilite/m-ui/src/assets",
"output": "/assets/"
}
]
}Usage
M-Theme
To enable light or dark themes, add the dark-theme or light-theme class to the <body> tag in your index.html:
<body class="dark-theme">
<!-- Your app content -->
</body>This theme provide custom palettes and provides the following variables:
$light-theme-background$light-theme-foreground$dark-theme-background$dark-theme-foreground
Example:
.my-container {
color: map-get($dark-theme-foreground, text);
}Some helper functions are also provided:
dark-color-overlay($elevation)light-color-overlay($elevation)
$elevation must be a value in [0, 1, 2, 3, 4, 6, 8, 12, 16, 24]
Example:
.my-container {
background: dark-color-overlay(16);
}Helper Functions and Variables
Variables
M-Theme provides pre-defined variables for customizing the look and feel of your app:
$light-theme-background$light-theme-foreground$dark-theme-background$dark-theme-foreground
Example:
.my-container {
color: map-get($dark-theme-foreground, text);
}Helper Functions
Use helper functions for overlays and dynamic styles:
dark-color-overlay($elevation)light-color-overlay($elevation)
Note $elevation must be one of [0, 1, 2, 3, 4, 6, 8, 12, 16, 24].
Example:
.my-container {
background: dark-color-overlay(16);
}Testing the Installation
- Ensure all configurations in angular.json are correctly applied.
- Use the imported SCSS variables and functions in your components to verify that they work as expected.
- If icons or assets aren't loading, double-check the assets array in angular.json.
M-ui
All library components are prefixed with m- and are designed as standalone components.
<m-icons type="accident" class="m-icon"></m-icons>Default import
We can import the entire library in our Angular module.
import {MIcons} from '@metromobilite/m-ui';
@NgModule({
declarations: [AppComponent],
imports: [MIcons],
bootstrap: [AppComponent]
})
export class AppModule {}Import unitary components
We can also import the components individually.
import {MIcons} from '@metromobilite/m-ui/m-icons';Note Add this in your tsconfig.json
"compilerOptions": { "paths": { "@metromobilite/m-ui/*": [ "node_modules/@metromobilite/m-ui", "node_modules/@metromobilite/m-ui/lib/*" ] } }