@felixdulfer/ngx-mat-period-picker

ngx-mat-period-picker

A Angular Material period picker component that allows users to select start and end periods with support for "present" periods.

Installation

npm install ngx-mat-period-picker

Usage

Basic Period Picker

import { PeriodPickerComponent } from "ngx-mat-period-picker";

@Component({
  selector: "app-example",
  template: `<ngx-mat-period-picker [(ngModel)]="period" startLabel="Start Date" endLabel="End Date" presentLabel="Present" />`,
})
export class ExampleComponent {
  period = {
    start: { year: 2020, month: 3 },
    end: { year: 2023, month: 12 },
    isPresent: false,
  };
}

Year/Month Field

import { YearMonthFieldComponent } from "ngx-mat-period-picker";

@Component({
  selector: "app-example",
  template: `<ngx-mat-year-month-picker [(ngModel)]="date" label="Select Date" placeholder="Choose a date" /> `,
})
export class ExampleComponent {
  date = { year: 2023, month: 6 };
}

Internationalization (i18n)

The startLabel and endLabel attributes are static properties that can be easily translated using Angular's built-in i18n solution.

Global Locale Configuration

The library automatically uses Angular's configured locale (LOCALE_ID or $localize.locale) by default. You can also override this with custom locale configuration if needed.

Basic Usage

Automatic (Recommended): The library automatically uses Angular's configured locale.

// In your app.config.ts or main.ts
import { LOCALE_ID } from '@angular/core';

bootstrapApplication(AppComponent, {
  providers: [
    { provide: LOCALE_ID, useValue: 'de-DE' }  // German locale
  ]
});

Manual Override: You can also override the locale explicitly:

import { provideNgxMatPeriodPicker } from 'ngx-mat-period-picker';

bootstrapApplication(AppComponent, {
  providers: [
    provideNgxMatPeriodPicker({
      locale: 'de-DE'  // Override to German locale
    })
  ]
});

Supported Locales

The library supports all locales that the browser's Intl API supports, including:

• en-US - English (United States)
• de-DE - German (Germany)
• es-ES - Spanish (Spain)
• fr-FR - French (France)
• it-IT - Italian (Italy)
• And many more...

What Gets Localized

When you configure a locale:

• Month names in picker dialogs (Jan, Feb, Mär, Apr...)
• Date formatting in display fields
• Month labels throughout components

For detailed configuration options, see Locale Configuration.

Basic Usage with i18n

<ngx-mat-period-picker
  startLabel="Start Date"
  endLabel="End Date"
/>

With Angular i18n

• Mark the labels for translation:

<ngx-mat-period-picker
  startLabel="Start Date"
  endLabel="End Date"
  i18n-startLabel="@@period.start.label"
  i18n-endLabel="@@period.end.label"
/>

• Extract messages:

ng extract-i18n --output-path src/locale

• Translate in your locale files:

{
  "period.start.label": "Fecha de inicio",
  "period.end.label": "Fecha de fin"
}

Custom Component with Translated Labels

You can also create a custom component that extends the period picker with pre-translated labels:

@Component({
  selector: "app-translated-period-picker",
  template: ` <ngx-mat-period-picker [startLabel]="'Start Date'" [endLabel]="'End Date'" i18n-startLabel="@@period.start.label" i18n-endLabel="@@period.end.label" /> `,
})
export class TranslatedPeriodPickerComponent extends PeriodPickerComponent {
  // Custom logic here
}

Configuration Options

Period Picker Inputs

Input	Type	Default	Description
startLabel	string	'Start Period'	Label for the start field
endLabel	string	'End Period'	Label for the end field
presentLabel	string	'Present'	Label for the present toggle
startPlaceholder	string	'Select start period'	Placeholder for start field
endPlaceholder	string	'Select end period'	Placeholder for end field
presentPlaceholder	string	'Present'	Placeholder when present is selected
baseYearStart	number | undefined	undefined	Base year for start field year picker
baseYearEnd	number | undefined	undefined	Base year for end field year picker
showPresentToggle	boolean	true	Whether to show the present toggle
width	string | number	'auto'	Fixed width of the period picker container
fullWidth	boolean	true	Whether to take full container width (automatically false when width is set)
fieldWidth	string | number	'200px'	Width of individual fields
fieldFullWidth	boolean	true	Whether fields should take full width

Year/Month Field Inputs

Input	Type	Default	Description
label	string	'Select Year/Month'	Field label
placeholder	string	'Click to select'	Field placeholder
minYear	number | undefined	undefined	Minimum selectable year
maxYear	number | undefined	undefined	Maximum selectable year
baseYear	number | undefined	undefined	Base year for year picker
disabled	boolean	false	Whether the field is disabled
presentLabel	string	'Present'	Label for present value
presentValue	boolean	false	Whether present is selected
showPresentToggle	boolean	false	Whether to show the present toggle
width	string | number	'200px'	Fixed width of the field
fullWidth	boolean	true	Whether to take full container width (automatically false when width is set)

Width Configuration

Automatic Behavior

When you set a width value (either as a number or string), the component automatically sets fullWidth to false. This ensures that:

• Fixed Width: When you specify a width, the component respects that exact width
• Full Width: When width is 'auto' (default), the component uses the fullWidth setting
• Smart Defaults: No need to manually coordinate width and fullWidth settings

Examples

Default Full Width Behavior:

<ngx-mat-period-picker
  startLabel="Start Date"
  endLabel="End Date"
/>

Fixed Width (Automatically Overrides fullWidth):

<ngx-mat-period-picker
  startLabel="Start"
  endLabel="End"
  [width]="500"
  // fullWidth automatically becomes false
/>

Explicit Override:

<ngx-mat-period-picker
  startLabel="Start"
  endLabel="End"
  [width]="500"
  [fullWidth]="true" // This will be ignored when width is set
/>

Layout Examples

Flex Layout (Default)

<ngx-mat-period-picker
  [layout]="'flex'"
  [fieldWidth]="250"
  startLabel="Start"
  endLabel="End"
/>

Fields are displayed side by side with equal flex distribution. Each field has a minimum width of 200px and will grow to fill available space.

Full Width Configuration

<ngx-mat-period-picker
  [fullWidth]="true"
  [fieldFullWidth]="true"
  startLabel="Start Date"
  endLabel="End Date"
/>

The period picker takes the full width of its container, and both fields expand to fill the available space equally.

Fixed Width Configuration

<ngx-mat-period-picker
  [width]="600"
  [fieldWidth]="250"
  startLabel="Start"
  endLabel="End"
/>

The period picker has a fixed width of 600px, and each field has a fixed width of 250px.

Data Types

YearMonth

interface YearMonth {
  year: number;
  month: number | null; // null for year-only selection
}

Period

interface Period {
  start: YearMonth | null;
  end: YearMonth | null;
  isPresent: boolean;
}

Styling

The components use CSS custom properties and can be customized with your own styles. Key CSS classes:

• .period-picker-container - Main container
• .period-fields - Container for start/end fields
• .year-month-field - Individual year/month field
• .full-width - Applied when fullWidth is true
• .layout-flex - Applied when layout is 'flex'
• .layout-grid - Applied when layout is 'grid'

Browser Support

• Angular 17+
• Modern browsers with CSS Grid and Flexbox support
• Mobile-responsive design

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

License

MIT License

API Reference

PeriodPickerComponent

Input	Type	Default	Description
startLabel	string	'Start Period'	Static label for the start field (supports i18n)
endLabel	string	'End Period'	Static label for the end field (supports i18n)
presentLabel	string	'Present'	Label for the present toggle
startPlaceholder	string	'Select start period'	Placeholder text for start field
endPlaceholder	string	'Select end period'	Placeholder text for end field
presentPlaceholder	string	'Present'	Placeholder text for present field
baseYearStart	number | undefined	undefined	Base year for start field year picker
baseYearEnd	number | undefined	undefined	Base year for end field year picker
showPresentToggle	boolean	true	Whether to show the present toggle
width	string | number	'auto'	Fixed width of the period picker container
fullWidth	boolean	true	Whether to take full container width (automatically false when width is set)
fieldWidth	string | number	'200px'	Width of individual fields
fieldFullWidth	boolean	true	Whether fields should take full width