Date & time¶

Usage¶

These components are used in scenarios where users need to input specific dates, times, or date ranges.

Date pickers typically include an expandable calendar menu and a text input field, while time pickers focus solely on time selection, usually a text input field or dropdown menu for selecting specific times.

When to use¶

• To collect absolute date and time inputs.
• For scheduling tasks.
• In forms.
• To select date ranges for generating reports or viewing historical data.
• For relative date selection, use date range filter.

Best practices¶

• Ensure the format of dates and times adheres to the user's locale settings. See localization for more details.
• Ensure placeholders are also localized to match the user's regional settings (e.g., "MM/DD/YYYY").
• When required, validation can be set for all time inputs.
• Provide clear and concise labels for input fields.

Design¶

Basic anatomy¶

Date pickers and date-time pickers consist of an optional input field and a calendar view. The input field allows users to manually type dates and times. When needed, the calendar view opens for visual selection, making this structure common across all variants.

1. Label (optional), 2. Input, 3. Calendar button, 4. Month & Year control, 5. Previous and Next month control, 6. Default day, 7. Selected day, 8. Current day, 9. Off month day, 10. Today control

Single date and date-time picker¶

The single date picker allows users to select a specific date, either by typing in the input field or using the calendar view. When the time option is enabled, users can also select a specific time.

Date and date-time range picker¶

The date range picker enables users to choose a start and end date. When the time option is enabled, a two-month view layout is used.

Time picker¶

The time picker is a component with separate input fields for individually setting units of time measurement (e.g., hh, mm, …). Minutes, seconds, and milliseconds are optional and can be configured to show or hide as needed.

Code¶

The datepicker and timepicker components are highly configurable. The datepicker optionally includes the timepicker.

The SiDatepickerComponent, SiTimepickerComponent, as well as the SiDatepickerDirective, to attach the datepicker component to a HTML input element, are provided by the SiDatepickerModule Angular module.

Usage¶

Datepicker can be imported using the module

import { SiDatepickerModule } from '@siemens/element-ng/datepicker';

@NgModule({
  imports: [SiDatepickerModule, ...]
})

or as a standalone component:

import {
  SiDateInputDirective,
  SiDatepickerComponent,
  SiDatepickerDirective,
  SiDateRangeComponent
} from '@siemens/element-ng/datepicker';

@Component({
  imports: [
    SiDateInputDirective,
    SiDatepickerComponent,
    SiDatepickerDirective,
    SiDateRangeComponent,
    ...
  ]
})

Datepicker without time¶

The datepicker component can be added to any view. Bidirectional binding of the date object is provided by the date property. The configuration is handled by the config object as documented in the API.

Datepicker with time control¶

• Setting showTime in the config will display the timepicker within the date picker.
• A switch enables the user to include (Consider time) the time or not (Ignore time).
• Initial switch enablement is controlled by the disabledTime flag and changes are emitted by the disabledTimeChange output property.
• Use the mandatoryTime flag to hide the switch.

Datepicker with date range¶

The si-datepicker allows to pick date ranges. Use the two-way binded property dateRange and set enableDateRange: true in configuration.

Input element with datepicker¶

The SiDatepickerDirective attaches the datepicker to an HTML input element. Without any additional configuration, the Angular locale date formatter is used to write the selected date into the input field. Changes of the input field are also parsed and used to set the date in the datepicker. Optionally, you can provide a custom date and time format using the config object.

The directive implements the Angular ControlValueAccessor and can be used in Angular Forms.

Input element with date range picker¶

The SiDateRangeComponent component is a custom component which can be used to use datepicker as range selector.

The component implements the Angular ControlValueAccessor and can be used in Angular Forms.

Timepicker¶

The timepicker component is a custom component with individual input fields for setting the parts of the time individually, like hours, and minutes. It implements the ControlValueAccessor and can be used in Angular Forms.

SiDatepickerComponent API Documentation¶

Input Properties¶

Output Properties¶

Attributes and Methods¶

SiDateRangeComponent API Documentation¶

Common interface for form item controls. Controls that should be connected to SiFormItemComponent must implement this interface and must be provided using the SI_FORM_ITEM_CONTROL token.

Input Properties¶

Output Properties¶

Attributes and Methods¶

SiTimepickerComponent API Documentation¶

Common interface for form item controls. Controls that should be connected to SiFormItemComponent must implement this interface and must be provided using the SI_FORM_ITEM_CONTROL token.

Input Properties¶

Output Properties¶

Attributes and Methods¶

SiDatepickerDirective API Documentation¶

Base directive for date input fields.

Input Properties¶

Output Properties¶

Attributes and Methods¶

Types Documentation¶

labelWidth="100px"

import { provideFormValidationErrorMapper } form '@siemens/element-ng/forms'

@Component({
  template: `<form>...</form>`
  providers: [provideFormValidationErrorMapper({
    'name.required': 'CUSTOM_REQUIRED_ERROR'
  })]
})
class MyFormComponent {}

<!-- Responsive column layout -->
<form class="responsive-form-col-layout">...</form>
<!-- Always column layout -->
<form class="form-col-layout">...</form>

scss
@use '@siemens/element-theme/src/styles/bootstrap/mixins/form-layout';

// Custom responsive breakpoint
.custom-form-col-layout {
  // Above 400px the column layout is used
  @include form-layout.responsive-form-col-layout(400px);
}

labelWidth="100px".