Dario Šoć

Angular Material v21 and Material Design 3 are here. This is the missing walkthrough to build a button you can actually ship.

Angular Material v21 Button Guide (Material Design 3)

Buttons are easy until they’re not.

The moment you need loading states, icons, variants, and theming that behaves across light and dark mode, “just use MatButton” turns into a bunch of one-off fixes scattered across the codebase.

In this post, I’m building a reusable button component using Angular v21 and Angular Material v21 (Material Design 3). The goal is a button you can drop anywhere and trust.

For the sake of simplicity, this blog post covers only outlined and filled button styles in the primary and secondary variants.


Here’s the plan

I’m splitting the work into three pieces:

 * a base directive for inputs and shared behavior
 * a loader directive that mounts a spinner only when needed
 * a small component that stays boring and reusable

If you want more background on Material theming, I previously covered the full theme setup in Angular Material 19. Many of the same concepts carry over here.


Button component preview











1. The base button directive

This is the foundation. BaseButton holds all shared inputs and computed state, so the component stays simple.

import { booleanAttribute, computed, input, Directive } from '@angular/core';

@Directive({
  host: {
    '[style.pointer-events]': 'pointerEvents()',
  },
})
export abstract class BaseButton {
  secondary = input(false, { transform: booleanAttribute });
  icon = input<string>();
  suffixIcon = input<string>();
  loading = input(false, { transform: booleanAttribute });
  disabled = input(false, { transform: booleanAttribute });
  disableRipple = input(false, { transform: booleanAttribute });
  isDisabled = computed(() => this.disabled() || this.loading());
  pointerEvents = computed(() => this.isDisabled() ? 'none' : 'auto');
  appearance = computed(() => this.secondary() ? 'outlined' : 'filled');
}



What matters here

Signal-based inputs keep state reactive:

icon = input<string>();
loading = input(false, {transform: booleanAttribute});


booleanAttribute lets you write clean HTML-style booleans:


<app-button [loading]="true">Save</app-button>
<app-button loading="true">Save</app-button>
<app-button loading>Save</app-button>


Computed signals keep derived logic in one place:

isDisabled = computed(() => (this.disabled() || this.loading()));


And the host binding prevents unwanted clicks while button is disabled or loading:

@Directive({
  host: {
    '[style.pointer-events]': 'pointerEvents()',
  },
})



2. The button loader directive

This directive is responsible for the loading experience. When loading is true, it creates a Material spinner and appends it to the button.

import {
  Directive,
  Renderer2,
  input,
  inject,
  ViewContainerRef,
  booleanAttribute,
  ComponentRef,
  afterRenderEffect,
  untracked
} from '@angular/core';
import { MatProgressSpinner } from '@angular/material/progress-spinner';

@Directive({
  selector: 'button[loading]',
})
export class ButtonLoaderDirective {
  loading = input(false, { transform: booleanAttribute });

  private viewContainer = inject(ViewContainerRef);
  private renderer = inject(Renderer2);

  private spinner: ComponentRef<MatProgressSpinner> | null = null;
  private readonly buttonNativeElement = signal<HTMLButtonElement>(
    this.viewContainer.element.nativeElement
  );
  private readonly spinnerSize = computed(() => {
    const buttonHeight = this.buttonNativeElement().clientHeight;
    return buttonHeight ? Math.trunc(buttonHeight / 1.5) : 20;
  })

  constructor() {
    afterRenderEffect({
      earlyRead: () => {
        if (this.buttonNativeElement().tagName !== 'BUTTON') {
          throw new Error(
          `ButtonLoaderDirective can only be used on a button element, but used on${this.buttonNativeElement().tagName}`
          );
        }
      },
      write: () => {
        const loading = this.loading();
        untracked(() => {
          if (loading) {
            this.buttonNativeElement().classList.add('button-loading');
            this.createSpinner();
          } else {
            this.buttonNativeElement().classList.remove('button-loading');
            this.destroySpinner();
          }
        });
      },
    });
  }

  private createSpinner(): void {
    if (!this.spinner) {
      this.spinner = this.viewContainer.createComponent(MatProgressSpinner);
      this.spinner.instance.diameter = this.spinnerSize();
      this.spinner.instance.mode = 'indeterminate';
      this.spinner.instance.strokeWidth = 2;
      const spinnerElement: HTMLElement = this.spinner.location.nativeElement;
      this.renderer.setStyle(spinnerElement, 'position', 'absolute');
      this.renderer.appendChild(this.buttonNativeElement(), spinnerElement);
    }
  }

  private destroySpinner(): void {
    this.spinner?.destroy();
    this.spinner = null;
  }
}





Understanding afterRenderEffect

This hook is meant for DOM manipulation. It runs after Angular finishes rendering and provide us with four phases (earlyRead, write, mixedReadWrite and read). We will use earlyRead and write phases.

Phase: earlyRead

earlyRead: () => {
  // Validate that directive is on correct element
  if (this.buttonNativeElement.tagName !== 'BUTTON') {
    throw new Error(...);
  }
}


Phase: write

write: () => {
  const loading = this.loading();
  untracked(() => {
    if (loading) {
      this.buttonNativeElement.classList.add('button-loading');
      this.createSpinner();
    } else {
      this.buttonNativeElement.classList.remove('button-loading');
      this.destroySpinner();
    }
  });
}



Why untracked()?

It prevents reactive dependencies from being created inside an effect. Let's take a look at this example:

If another signal was tracked within afterRenderEffect and subsequently updated inside the createSpinner function, not wrapping it in untracked() would result in an infinite loop:

❌

// Creates infinite loop
write: () => {
  if (this.loading()) { // Tracks loading signal
    this.createSpinner(); // Might trigger effect (in our case it don't)
  }
}


✅

// Reads signal once, no tracking
write: () => {
  const loading = this.loading(); // Tracks once
  untracked(() => {
    if (loading) {
      this.createSpinner(); // No tracking inside untracked
    }
  });
}



3. Dynamic component creation

The spinner is created dynamically using ViewContainerRef.

private createSpinner(): void {
  if (!this.spinner) {
    // Create component instance
    this.spinner = this.viewContainer.createComponent(MatProgressSpinner);

    // Configure spinner properties
    this.spinner.instance.diameter = this.spinnerSize;
    this.spinner.instance.mode = 'indeterminate';
    this.spinner.instance.strokeWidth = 2;

    // Set spinner styles
    const spinnerElement: HTMLElement = this.spinner.location.nativeElement;
    this.renderer.setStyle(spinnerElement, 'position', 'absolute');

    // Insert into DOM
    this.renderer.appendChild(this.buttonNativeElement(), spinnerElement);
  }
}


Spinner size stays proportional by tying it to button height:

get spinnerSize(): number {
  const buttonHeight = this.buttonNativeElement.clientHeight;
  return buttonHeight ? Math.trunc(buttonHeight / 1.5) : 20;
}



4. The button component

With the directives in place, the component stays small.


Component

import { ChangeDetectionStrategy, Component } from '@angular/core';
import { MatButtonModule } from '@angular/material/button';
import { MatIconModule } from '@angular/material/icon';
import { BaseButton } from '../base-button.directive';
import { ButtonLoaderDirective } from '../button-loader.directive';
import { NgClass } from '@angular/common';

@Component({
  selector: 'app-button',
  templateUrl: 'button.component.html',
  styleUrls: ['button.component.scss'],
  imports: [NgClass, MatButtonModule, MatIconModule, ButtonLoaderDirective],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ButtonComponent extends BaseButton {}



Template

<button
  [ngClass]="{ 'primary': !secondary(), 'secondary': secondary() }"
  [matButton]="appearance()"
  [disabled]="isDisabled()"
  [disableRipple]="disableRipple()"
  [loading]="loading()"
>
  @if (icon()) { <mat-icon>{{icon()}}</mat-icon> }
  <ng-content></ng-content>
  @if (suffixIcon()) { <mat-icon iconPositionEnd>{{suffixIcon()}}</mat-icon> }
</button>



5. Dynamic Mat Button appearance

Material buttons use the matButton input. The directive switches between “filled” and “outlined”.

type MatButtonAppearance = 'text' | 'filled' | 'elevated' | 'outlined' | 'tonal';

[matButton]="appearance()" // matButton is MatButtonAppearance type


Equivalent to:


<button matButton="filled">...</button>


<button matButton="outlined">...</button>


<button matButton="text">...</button>



6. Styling with SCSS

This is where M3 theming pays off. The styles are built around mat.button-overrides() and native light-dark().

@use '@angular/material' as mat;

@mixin button($spinner-color-light: #FFFFFF, $spinner-color-dark: #A8ACB1)
  {
  width: 100%;
  &.button-loading {
    @include button-loading($spinner-color-light, $spinner-color-dark);
  }
}

@mixin button-loading($spinner-color-light, $spinner-color-dark) {
  @include mat.progress-spinner-overrides((
    active-indicator-color: light-dark(
      $spinner-color-light,
      $spinner-color-dark
    ),
  ));

  @include mat.button-overrides((
    filled-disabled-label-text-color: transparent,
    filled-label-text-color: transparent,
    outlined-label-text-color: transparent,
    outlined-disabled-label-text-color: transparent,
  ));
}

:host {
  display: contents;
  .primary {
    @include button;
    @include mat.button-overrides((
      filled-container-color: light-dark(#4a3b6b, #9b8abf),
      filled-label-text-color: #FFFFFF,
      filled-disabled-container-color: light-dark(#4a3b6b60, #9b8abf60),
      filled-disabled-label-text-color: light-dark(#FFFFFF, #A8ACB1),
      filled-label-text-size: 14px,
      filled-state-layer-color: light-dark(#5d4d80, #b0a1cf),
      filled-hover-state-layer-opacity: 1,
      filled-focus-state-layer-opacity: 1,
      filled-pressed-state-layer-opacity: 1,
    ));
  }

  .secondary {
    @include button($spinner-color-light:#082234);
    @include mat.button-overrides((
      outlined-outline-color: light-dark(#B5BEC5, #A8ACB1),
      outlined-label-text-color: light-dark(#082234, #E6E1E3),
      outlined-state-layer-color: transparent,
      outlined-ripple-color: transparent,
      outlined-disabled-outline-color: light-dark(#B5BEC5, #A8ACB180),
    ));

    &:hover, &:active {
      @include mat.button-overrides((
        outlined-outline-color: light-dark(#475A66, #E6E1E3),
      ));
    }

    &:focus, &:active {
      @include mat.button-overrides((
        outlined-ripple-color: light-dark(#4a3b6b30, #9b8abf40),
        outlined-state-layer-color: light-dark(#4a3b6b15, #9b8abf20),
        outlined-focus-state-layer-opacity: 1,
      ));
    }
  }
}



mat.button-overrides()

@include mat.button-overrides((
  filled-container-color: #4a3b6b,
  filled-label-text-color: #FFFFFF,
  filled-hover-state-layer-opacity: 1,
));



light-dark() and color-scheme

filled-container-color: light-dark(#4a3b6b, #9b8abf)
//                                ↑ light  ↑ dark


// In your global styles
:root {
  color-scheme: light dark;
}



display: contents for layout

:host {
  display: contents;
  // ... other styles
}


This makes the component wrapper “disappear” for layout purposes:


<div style="display: grid;">
  <app-button> 
  <button>Click me</button>
  </app-button>
</div>

<div style="display: grid;">
  <app-button style="display: contents;"> 
  <button>Click me</button> 
  </app-button>
</div>



Loading state styling

@mixin button-loading($spinner-color-light, $spinner-color-dark) {
  @include mat.button-overrides((
    filled-label-text-color: transparent, // Hide text
    outlined-label-text-color: transparent,
  ));
}



7. Understanding state layers

Material uses state layers tokens for interaction feedback.

filled-state-layer-color: #5d4d80, // The overlay color
filled-hover-state-layer-opacity: 1, // Opacity on hover
filled-focus-state-layer-opacity: 1, // Opacity on focus
filled-pressed-state-layer-opacity: 1, // Opacity when pressed
outlined-state-layer-color: transparent, // The overlay color
outlined-focus-state-layer-opacity: 1 // Opacity on focus



8. Usage examples


Basic usage

@Component({
  template: `
    <app-button (click)="onSave()">
      Save
    </app-button>
  `
})
export class MyComponent {
  onSave() {
    console.log('Saving...');
  }
}



With icons


<app-button icon="add">
  Create New
</app-button>


<app-button suffixIcon="arrow_forward">
  Next Step
</app-button>


<app-button icon="download" suffixIcon="arrow_drop_down">
  Export
</app-button>



Loading state

@Component({
  template: `
    <app-button [loading]="isLoading()" (click)="onClick()">
      Submit
    </app-button>
  `
})
export class MyComponent {
  isLoading = signal(false);

  onClick() {
    this.isLoading.set(true);
    // Simulate API call
    setTimeout(() => {
      this.isLoading.set(false);
    }, 2000);
  }
}



Disabled state

<app-button [disabled]="!form.valid">
  Submit
</app-button>



Secondary variant

<app-button secondary>
  Cancel
</app-button>



9. Complete example

@Component({
  selector: 'app-root',
  template: `
    <section class="button-section">
      <h2>Primary Buttons</h2>
      <div class="button-grid">
        
        <app-button (click)="onClick()" [loading]="isLoading()">
          Confirm
        </app-button>
    
        
        <app-button icon="add" (click)="onClick()" [loading]="isLoading()">
          Confirm
        </app-button>
    
        
        <app-button suffixIcon="add" (click)="onClick()" [loading]="isLoading()">
          Confirm
        </app-button>
    
        
        <app-button suffixIcon="add" [loading]="true">
          Confirm
        </app-button>
        
        
        <app-button icon="add" disabled>
          Confirm
        </app-button>
      </div>
    </section>
    <section class="button-section">
      <h2>Secondary Buttons</h2>
      <div class="button-grid">
        <app-button secondary (click)="onClick()" [loading]="isLoading()">
          Cancel
        </app-button>
  
        <app-button secondary icon="close">
          Dismiss
        </app-button>
      </div>
    </section>
  `,
  imports: [ButtonComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class AppComponent {
  isLoading = signal(false);

  onClick() {
    this.isLoading.set(true);
    setTimeout(() => {
      this.isLoading.set(false);
    }, 2_000);
  }
}



10. Tips and gotchas


1. display: contents for layout

:host {
  display: contents;
}



2. Pointer events on disabled loading buttons

@Directive({
  host: {
    '[style.pointer-events]': 'pointerEvents()',
  },
})



4. booleanAttribute transform

loading = input(false, {transform: booleanAttribute});


<app-button loading="true">Save</app-button>
<app-button loading>Save</app-button> 



5. OnPush change detection

@Component({
  changeDetection: ChangeDetectionStrategy.OnPush,
})



6. Standalone everything

@Component({
  imports: [NgClass, MatButtonModule, MatIconModule, ButtonLoaderDirective],
  // No need for declarations or module imports
})



What’s next?

You could extend this component with:

 * Icon-only buttons (no text)
 * Button groups and toolbars
 * Different sizes (small, medium, large)
 * More variants (text, raised, etc.)
 * Loading state with progress percentage


Wrapping up

If you’ve built shared UI components in Angular before, you already know where the time goes: repeated edge cases, slightly different variants, and behavior that drifts across the app.

This setup keeps the behavior in one place, keeps the component thin, and lets Material 3 theming do the styling work. The button stays predictable, which is the main thing you want from a shared component.


Resources

Angular Documentation
Material Design 3 Guidelines
Angular Material Components
MDN: light-dark() Function

Development

Angular Material v21: a reusable button component (M3)

Learn how to set up light/dark themes, customize tokens, and style Angular Material 19 components using the new Material 3 theming API — no hacks needed.

How to Customize Angular Material 19 Themes the Right Way

Angular 18 introduced full support for Material 3, using design tokens implemented as CSS custom properties. This lets developers style components without relying on deep selectors or high-specificity overrides.

With Angular Material 19, the theming system gets a new API that makes customizing your app's look and feel much simpler. You get a clean, structured way to define colors, typography, and component behavior.

In this post, I’ll walk through practical tips for setting up themes quickly, and handling both global and component-level style overrides.

Here's what I used for this:

 * @angular/cli: 19.2.7
 * @angular/material: 19.2.7

npm i -g @angular/cli
ng new angular-material-19 --style scss




When prompted:







Prompt
Your Input





Do you want to enable Server-Side Rendering (SSR) and Static Site Generation?

N








cd angular-material-19
ng add @angular/material




Next, choose:







Prompt
Your Input





The package @angular/material@19.2.7 will be installed and executed.
Would you like to proceed? (Y/N)

Y



Choose a prebuilt theme name, or "custom" for a custom theme:

Custom



Set up global Angular Material typography styles? (Y/N)

Y








Nice — the Angular project is up and running. Now it’s time to define the theme.

You can stick with one of the predefined Material color palettes, or go custom if you want more control. The only required color is primary, while secondary, tertiary, error and neutral colors are optional but recommended for a more refined design, also specify path and type of file(css/scss).

To generate a custom palette, run:

ng generate @angular/material:theme-color



Define the Theme in styles.scss

Let's open the src/styles.scss file and define our theme.

@use '@angular/material' as mat;
// in case of using custom theme replace with the actual file path
@use './path/to/_theme-colors' as my-theme;

html {
	@include mat.theme((
		color: mat.$violet-palette,
		// or using custom theme:
		color: (
		  primary: my-theme.$primary-palette,
		  tertiary: my-theme.$tertiary-palette,
		),
		typography: Roboto,
		// or using typography map:
		typography: (
		  plain-family: Roboto, // most of the components text
    	  brand-family: Open Sans, // mostly for titles and headings
    	  bold-weight: 800,
    	  medium-weight: 400,
    	  regular-weight: 200,
        ),
		density: 0 // from 0 to -5
    ))
}

html, body { height: 100%; }
body { 
	font-family: Roboto, "Helvetica Neue", sans-serif;
}
* {
	box-sizing: border-box;
	margin: 0;
}



With the theme in place, let’s add light and dark mode support.

We’ll hook into system color variables to set default background and text colors — no manual toggling needed.

(We’ll cover more about overriding system variables a bit later.)

@use '@angular/material' as mat;

html {
	color-scheme: light dark; // add color-scheme css property
	@include mat.theme((
		color: mat.$violet-palette,
		typography: Roboto,
		density: 0
	), $overrides: (
		surface: light-dark(#fefbff, #211f21), // override system variable
		on-surface: light-dark(#1c1b1d, #e6e1e3), // override system variable
	));
}

html, body { height: 100%; }
body {
	// Add default background and text colors
	background: var(--mat-sys-surface); // using system variables
	color: var(--mat-sys-on-surface);
	font-family: Roboto, "Helvetica Neue", sans-serif;
}
* {
	box-sizing: border-box;
	margin: 0;
}




Angular Material System Variables

Angular Material components rely on a set of system variables — defined as CSS custom properties via the material.theme mixin.

They come in three flavors: colors, typography, and elevation.

These variables follow the Material Design 3 spec, giving you a solid foundation that’s flexible and easy to extend.


🎨 Colors system variables

Based on MD 3 color system.

Most commonly used color variable within Angular Material components:







Token
CSS Variables
Description




Primary

--mat-sys-primary
--mat-sys-on-primary


Most common color used by Angular Material. Used for the background of filled buttons, icon color of selected radio buttons, and outline of form fields.



Surface

--mat-sys-surface
--mat-sys-on-surface


Used for the background color of the app and most components such as dialogs, cards, and tables.



Error

--mat-sys-error
--mat-sys-on-error


Used for the background of badges and the text color of invalid form field inputs.



Outline

--mat-sys-outline
--mat-sys-outline-variant


Used for dividers and the border color of outlined form fields.











—-mat-sys- color variable is usually paired with —-mat-sys-on- color which is used for icons, text, and other visual elements placed on an —-mat-sys- background.

Here’s an example of color system variables in use:

body {
	background: var(--mat-sys-surface);
	color: var(--mat-sys-on-surface);
}




Besides these, there are additional color system variables.


🅰️ Typography system variables

Based on MD 3 typography system.

Material Design 3 defines five typography categories: body, display, headline, label, and title — each with three sizes: small, medium, and large.

Next, we’ll walk through a few examples of how to use these typography variables in practice.







Category
CSS Variables
Usage




Display

--mat-sys-display-small
--mat-sys-display-medium
--mat-sys-display-large


Largest text on screen, meant for short, high-impact content or numbers.
Angular Material components currently don’t use these by default.



Headline

--mat-sys-headline-small
--mat-sys-headline-medium
--mat-sys-headline-large


For short, high-emphasis text.
Example: Dialog headers use `--mat-sys-headline-small`.



Title

--mat-sys-title-small
--mat-sys-title-medium
--mat-sys-title-large


Medium-emphasis text.
Examples:
• `--mat-sys-title-small`: Table headers, tab labels
• `--mat-sys-title-medium`: Expansion panel headers
• `--mat-sys-title-large`: Toolbar titles



Body

--mat-sys-body-small
--mat-sys-body-medium
--mat-sys-body-large


For longer passages of text.
Example: Dialog body text uses `--mat-sys-body-medium`.



Label

--mat-sys-label-small
--mat-sys-label-medium
--mat-sys-label-large


Smaller text for inline elements or component text.
Example: Buttons use `--mat-sys-label-large`.











Using Angular Material typography system tokens recomended by Angular Material team:

h1 {
	font: var(--mat-sys-display-large);
}
h2 {
	font: var(--mat-sys-display-medium);
}




You can customize any typography system variable by appending keywords like font, line-height, size, tracking, or weight.

That said, directly overriding these system variables isn’t recommended.

I’ll show you the cleaner, more flexible approach using a mixin a bit later in the post.


🏔️ Elevation system variables

Based on MD 3 elevation system.

Material Design defines six elevation levels to help create depth and visual hierarchy in your UI.







Elevation
CSS Variables
Usage




Level

--mat-sys-level0
--mat-sys-level1
--mat-sys-level2
--mat-sys-level3
--mat-sys-level4
--mat-sys-level5


Example: --mat-sys-level3 is used for the box-shadow of a FAB button.










Angular material tokens

To override tokenized styles, Angular Material gives you two powerful tools: system tokens and component tokens.


System Tokens

You can override system variables in two ways:

 1. Using the mat-theme-overrides mixin
 2. Passing an $overrides map directly into the mat.theme() definition

Both approaches work — it really comes down to personal preference.

Option 1: mat-theme-overrides

@include mat.theme-overrides((
  surface: light-dark(#fefbff, #211f21),
	on-surface: light-dark(#1c1b1d, #e6e1e3),
	display-large: 500 3.5rem/4rem Arial,
	level3: 0 4px 6px 1px var(--mat-sys-secodary)
));




Option 2: Overrides inside mat.theme()

@include mat.theme((
	color: mat.$violet-palette,
	typography: Roboto,
	density: 0
), $overrides: (
	surface: light-dark(#fefbff, #211f21), // --mat-sys-surface
	on-surface: light-dark(#1c1b1d, #e6e1e3), // --mat-sys-on-surface
	display-large: 500 3.5rem/4rem Arial, // --mat-sys-display-large
	level3: 0 4px 6px 1px var(--mat-sys-secodary) // --mat-sys-level3
));





Component Tokens

Each Angular Material component exposes an override mixin that lets you tweak token-based styles — including color, typography, and density.

You’ll find the full override API for each component in the Angular Material docs, under the “Styling” tab (new in v19).

Here’s a quick example using the button override API for mat-flat-button — and you can explore the full list of button tokens here.

@use '@angular/material' as mat;

// Customize the entire application by targeting :root. If you prefer to scope
// the style, user desired selector or style file.
:root {
  @include mat.button-overrides((
	// background and label color
    filled-container-color: light-dark(#082234, #775c89),
    filled-label-text-color: #FFFFFF,
    // disabled background and label color
    filled-disabled-container-color: light-dark(#08223480, #775c8980), 
    filled-disabled-label-text-color: light-dark(#FFFFFF, #A8ACB1),
    // label size
    filled-label-text-size: 14px,
    // color used for hover, focus and active state of button
    filled-state-layer-color: light-dark(#475A66, #8f719d),
    // opacity for button hover state
	filled-hover-state-layer-opacity: 1,
  ));
}





That’s a wrap on theming (for now)

With Angular 19 and full Material 3 support, customizing your app’s design is smoother and more flexible than ever. The new theming APIs, along with system and component tokens, give you the control to build consistent, polished UIs without messy CSS overrides.

In the next post, I’ll dig into advanced button styling: how to override tokens for different variants, handle states like hover and disabled, and apply consistent design patterns across your app.

Got feedback or want to share how you're using Material 3 theming? Drop us a note at hello@prototyp.digital.

Happy theming! 🎨

Mastering Angular Material 19 (Material 3): Theme Setup and Component Styling

How alias imports in React Native help streamline and organize your project.

React Native projects often become cluttered with complex import statements, impacting readability and development speed. Alias imports offer a streamlined solution, enhancing your code's structure and simplicity.

In this post, we'll explore the common challenges developers face with messy imports in React Native projects and introduce you to the world of alias imports. Alias imports offers a cleaner and more maintainable approach to structuring your import statements. Say goodbye to import chaos and hello to a more organized and efficient React Native codebase!


Understanding Alias Imports

Alias imports in React Native allow you to shorten and clarify file paths or modules. Instead of lengthy import paths, you can use concise, descriptive aliases.

This not only makes your code cleaner but also more readable. For instance, compare these two import statements:

Traditional:

import { SomeComponent } from '../../../components/someComponent';


With Alias:

import { SomeComponent } from '@components;


Alias imports allow you to define shorter and more descriptive names for file paths or modules. Instead of grappling with lengthy import paths that resemble a roadmap, you can create aliases that streamline your code and enhance its readability.


Setting Up Alias Imports

To implement alias imports, start with your project's structure. For example:

Next step is to add "baseURL" within "complierOptions" and configure "paths" as following in our tsconfig.json file:

{
 "extends": "@tsconfig/react-native/tsconfig.json",
 "compilerOptions": {
   "baseUrl": "src",
   "paths": {
     "@components": ["components/index"],
     "@modules/*": ["modules/*"],
     "@views/*": ["views/*"]
   }
 }
}

Now we need to add Babel Module Resolver package to our project dev dependencies:

NPM:

npm install --save-dev babel-plugin-module-resolver

YARN:

yarn add --dev babel-plugin-module-resolver

With the module resolver in place, the next step is to configure Babel to recognize and apply our alias imports. If you already have a babel.config.js file, great! Open it. If not, create a file named babel.config.js at the root of your project (or if you prefer, you can use a .babelrc file).


Now, add the following lines to your babel.config.js file:

plugins: [
   // ..other plugins if any
   [
     'module-resolver',
     {
       root: ['./src'],
       extensions: ['.js', '.ts', '.jsx', '.tsx', '.json'],
       alias: {
	  '@components: './src/components/index,
	  '@modules': './src/modules',
         '@views': './src/views',
       },
     },
   ],
 ],

With these steps completed, you've successfully configured alias imports in your React Native project.


It's now time to look at practical examples of alias imports in action:

import { Button } from '@components;
import { Block } from '@prototyp/skeletor';
import React from 'react';


export const QrScanner: React.FC = () => {
 return (
   <Block>
     ..rest of the component code
     <Button />
   </Block>
 );
};

import { Button, Input } from '@components;
import { QrScanner } from '@modules/QrScanner;
import { Screen } from '@prototyp/skeletor';
import React from 'react';


export const ConfirmTicket: React.FC = () => {
 return (
   <Screen>
     ..rest of the component code
     <QrScanner />
     <Button />
     <Input />
   </Screen>
 );
};

import { SkeletorProvider } from '@prototyp/skeletor';
import { ConfirmTicket } from '@views/ConfirmTicket;
import React from 'react';


export const App: React.FC = () => {
 return (
   <SkeletorProvider>
     <ConfirmTicket />
   </SkeletorProvider>
 );
};


Simplified Troubleshooting Guide:

Encounter issues? Here's how to troubleshoot common problems with alias imports:

 1. Caching Issues: Steps to reset cache with commands.
 2. Path Resolution: Tips for ensuring correct paths.
 3. Babel Configuration: Key points to check in your configuration.

1. Caching Woes: Changes Not Reflecting

If you find that changes to your alias configurations are not taking effect, it might be a caching issue. Babel and other tools might cache the configurations. To resolve this, try clearing the cache. You can do this by running the following commands:

NPM:

npm start -- --reset-cache


YARN:

 yarn start --reset-cache

If that don’t help restart TS server/reload window then delete/install node_modules and remove all watches and associated triggers:

rm -rf node_modules && yarn/npm i && watchman watch-del-all

Now start Metro with `–reset-cache` options again and build the app.


2. Incorrect Path Resolution

Double-check the paths in your alias configurations. A small typo can lead to import errors. Ensure that the paths are relative to your project root or provide the correct path structure.

3. Babel Configuration Errors

In your `babel.config.js`or `.babelrc file`, ensure that the syntax is correct. A misplaced comma or a missing bracket can lead to unexpected behavior. Use a linter or a code editor with syntax highlighting to catch any configuration errors.


Recap time

Alias imports in React Native make your developer life easier. They simplify import statements, enhance code readability, and streamline project structure. By adopting this practice, you can significantly reduce development complexity and improve maintenance efficiency. The key to mastering alias imports lies in understanding their setup, application, and troubleshooting.

Embrace these techniques to elevate your React Native development to the next level.

Next Steps: Want to further enhance your React Native experience? Explore our in-house toolkit, @prototyp/skeletor, designed to rid ourselves of any/all growing pains we have when working on a new react-native project, whether it’s building screen layouts, handling forms, animating stuff on screen or the usual platform-specific pains. Let's always improve the way we develop with React Native!




AuthorDario Šoć

Start a Project