M-UI is a component library built on top of Angular Material 19, 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.
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.
- 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.
- 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.
M-UI depends on Angular Material and Angular CDK. We need to install these dependencies before installing M-UI.
Peer Dependency | Version |
---|---|
@angular/common | 19.1.5 |
@angular/cdk | 19.1.5 |
@angular/core | 19.1.5 |
@angular/material | 19.1.5 |
- Install via npm
Run the following command to install the latest version of the library:
npm i @metromobilite/m-ui@latest
Note The
stylePreprocessorOptions
inangular.json
allows you to define custom paths for Sass to search for files during@use
or@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"]
}
}
}
}
}
}
}
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/assets/",
"output": "./assets/"
}
]
}
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.
@use "@metromobilite/m-ui/Mtheme" as Mtheme;
:root{
@include Mtheme.init();
}
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/assets",
"output": "/assets/"
}
]
}
Add this line in styles.scss to apply Material styles and colors:
@use "@metromobilite/m-ui/Mtheme" as Mtheme;
Note This: Loads the dark theme by default. Automatically switches to the light theme based on the user's system preferences (prefers-color-scheme: light). Applies Angular Material global styles and typography.
Mtheme automatically handles theme switching based on:
html{
@include Mtheme.init();
}
Note 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.
Notes User preferences (dark mode is enabled by default)
Forcing Light/Dark Mode Add the .light or .dark class to the
element:<body class="dark">
<!-- Your content here -->
</body>
If your application requires theme-specific styling for components, use @content inside the Mtheme.init() call.
Inject additional styles into Mtheme.init() as follows:
@include Mtheme.init() using($theme) {
@include demo.all-component-themes($theme);
};
Use the mat.get-theme-type() function to get the current theme type. This function returns either dark or light.
mat.get-theme-type($theme);
@mixin all-component-themes($theme) {
$themeType: mat.get-theme-type($theme);
// $themeType is dark or light
}
All library components are prefixed with m-
and are designed as standalone components.
<m-icons type="accident" class="m-icon"></m-icons>
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 {}
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/*" ] } }