# Date

Local date or date and time input with a calendar, display mask, and validation.

URL: https://webrad.atentor.com/docs/date
Updated: 2026-11-07

WebDate · Standard · Visual · 6 events

## Quick start

Add **Date1** in the Designer. Use the example in a page method.

```ts
Date1.mode = 'date';
Date1.dateFormat = 'dd/MM/yyyy';
Date1.required = true;
Date1.min = '2026-01-01';
Date1.max = '2026-12-31';
Date1.value = '2026-11-04';
Date1.onChange = (sender) => {
  if (sender.valid) console.log(sender.value, sender.text);
};
```

Date values represent local calendar fields, not UTC timestamps. An incomplete or impossible date has an empty value; use text to inspect the draft and valid to check required and range rules.

## Configure a date field

1. Add **Date** from the palette and select it in the Designer.
2. In the Inspector, choose **Mode**: date or datetime. Set **Date format** to dd/MM/yyyy, MM/dd/yyyy, or yyyy-MM-dd; enable **Show seconds** for datetime when needed.
3. Set the accessible label, optional placeholder, required and read-only settings, and whether to show the calendar. Configure value, min, and max using local ISO values; the limits are inclusive.
4. Link **OnInput** for typing and **OnChange** for a committed change in Interaction. The calendar can also be opened with Alt+Down or showPicker().

## Values and validation

The displayed mask follows the selected format and mode. value uses YYYY-MM-DD or local YYYY-MM-DDTHH:mm[:ss], independent of the display format. These are local calendar fields with no time zone or UTC conversion. text contains the displayed draft, including incomplete or impossible dates; value is empty for such drafts. date returns a local Date at the start of the day, while datetime includes the time; both return null for invalid or incomplete input.

Use valid or checkValidity() before processing input and reportValidity() to show the browser's validation message. required, min, and max participate in validation. clear() clears the field and setNow() uses the current local date and time. Runtime assignments affect the current instance; configure the Inspector to save project defaults.

## More examples

Date and time with validation

```ts
Date1.mode = 'datetime';
Date1.dateFormat = 'MM/dd/yyyy';
Date1.showSeconds = true;
Date1.min = '2026-01-01T09:00:00';
Date1.max = '2026-12-31T18:00:00';
Date1.value = '2026-11-04T14:30:00';
if (Date1.reportValidity()) {
  console.log(Date1.value, Date1.text, Date1.datetime);
}
```

Calendar and current date

```ts
Date1.mode = 'date';
Date1.setNow();
if (!Date1.showPicker()) console.log('Calendar is unavailable');
// Date1.clear();
```

## Inspector properties

Component options and defaults. Fields without runtime access are configured in the Inspector.

| Property / source | Type and options | Default | Runtime access |
| --- | --- | --- | --- |
| `name` — Name · Identity | `string` | `—` | name |
| `x` — Left · Size & position | `number` | `0` | x |
| `y` — Top · Size & position | `number` | `0` | y |
| `width` — Width · Size & position | `number` | `240` | width |
| `height` — Height · Size & position | `number` | `36` | height |
| `itemWidth` — Responsive width · Responsive size — Fit content grows the item to its widest rendered child and preserves child intrinsic widths; minimum and maximum width remain limits. | `enum` — `fixed` `stretch` `fit-content` | `"fixed"` | Inspector / configuration |
| `itemHeight` — Responsive height · Responsive size — Fit content grows the item to its lowest rendered child and preserves child intrinsic heights; minimum and maximum height remain limits. | `enum` — `fixed` `stretch` `fit-content` | `"fixed"` | Inspector / configuration |
| `itemMinWidth` — Minimum width · Responsive size | `number` | `0` | Inspector / configuration |
| `itemMaxWidth` — Maximum width · Responsive size | `number` | `null` | Inspector / configuration |
| `itemMinHeight` — Minimum height · Responsive size | `number` | `0` | Inspector / configuration |
| `itemMaxHeight` — Maximum height · Responsive size | `number` | `null` | Inspector / configuration |
| `itemGrow` — Grow · Responsive size | `number` | `0` | Inspector / configuration |
| `itemShrink` — Shrink · Responsive size — Allows fixed and stretch flow items to yield space. Fit-content keeps its intrinsic size so its children are not compressed. | `boolean` | `true` | Inspector / configuration |
| `itemAlignSelf` — Item alignment · Responsive size — Cross-axis alignment for this item in a row or column. Auto inherits the parent alignment; responsive cross-axis stretch retains its sizing behavior. | `enum` — `auto` `start` `center` `end` `stretch` | `"auto"` | Inspector / configuration |
| `itemHorizontalAnchor` — Horizontal anchor · Anchors & offsets | `enum` — `start` `center` `end` `stretch` | `"start"` | Inspector / configuration |
| `itemVerticalAnchor` — Vertical anchor · Anchors & offsets | `enum` — `start` `center` `end` `stretch` | `"start"` | Inspector / configuration |
| `itemLeft` — Left inset · Anchors & offsets | `number` | `0` | Inspector / configuration |
| `itemRight` — Right inset · Anchors & offsets | `number` | `0` | Inspector / configuration |
| `itemTop` — Top inset · Anchors & offsets | `number` | `0` | Inspector / configuration |
| `itemBottom` — Bottom inset · Anchors & offsets | `number` | `0` | Inspector / configuration |
| `margin` — Margin · Spacing — Outer spacing on all four sides, in pixels. Row and column layouts include this spacing between components. | `number` | `0` | margin |
| `marginTop` — Margin top · Spacing — Outer spacing on this side, in pixels. Overrides the shared Margin value. | `number` | `0` — Derived from saved properties | marginTop |
| `marginRight` — Margin right · Spacing — Outer spacing on this side, in pixels. Overrides the shared Margin value. | `number` | `0` — Derived from saved properties | marginRight |
| `marginBottom` — Margin bottom · Spacing — Outer spacing on this side, in pixels. Overrides the shared Margin value. | `number` | `0` — Derived from saved properties | marginBottom |
| `marginLeft` — Margin left · Spacing — Outer spacing on this side, in pixels. Overrides the shared Margin value. | `number` | `0` — Derived from saved properties | marginLeft |
| `visible` — Visible · Behavior | `boolean` | `true` | visible |
| `collapseWhenHidden` — Collapse when hidden · Behavior — Removes the component from the layout while it is not visible. | `boolean` | `true` | collapseWhenHidden |
| `enabled` — Enabled · Behavior | `boolean` | `true` | enabled |
| `tabIndex` — TabIndex · Behavior | `number` | `0` | tabIndex |
| `mode` — Mode · Date & time — Date only, or a local date and time without automatic UTC conversion. | `enum` — `date` `datetime` | `"date"` | mode |
| `dateFormat` — Date format · Date & time — Display and typing mask. The canonical value always uses ISO calendar fields. | `enum` — `dd/MM/yyyy` `MM/dd/yyyy` `yyyy-MM-dd` | `"dd/MM/yyyy"` | dateFormat |
| `showSeconds` — Show seconds · Date & time | `boolean` | `false` | showSeconds — Conditional availability in the Inspector |
| `value` — Value · Data — Empty, YYYY-MM-DD, or local YYYY-MM-DDTHH:mm[:ss]. The display uses the selected mask. | `string` | `""` | value |
| `min` — Minimum · Validation — Inclusive lower limit in local ISO format; empty removes the limit. | `string` | `""` | min |
| `max` — Maximum · Validation — Inclusive upper limit in local ISO format; empty removes the limit. | `string` | `""` | max |
| `required` — Required · Validation | `boolean` | `false` | required |
| `readOnly` — Read Only · Behavior | `boolean` | `false` | readOnly |
| `showCalendar` — Show calendar · Appearance | `boolean` | `true` | showCalendar |
| `placeholder` — Placeholder · Appearance — Empty displays the selected mask. | `string` | `""` | placeholder |
| `accessibleLabel` — Accessible label · Accessibility — Empty uses the component name. | `string` | `""` | accessibleLabel |
| `currentRowBindings` — Current row · Data — Bind writable visual values to fields of this repeated row. | `current-row-bindings` — Editor: current-row-bindings | `[]` | currentRowBindings |

## API in code

| Member | Signature | Access |
| --- | --- | --- |
| `mode` | `get mode(): WebDateMode;` | Read and write |
| `dateFormat` | `get dateFormat(): WebDateFormat;` | Read and write |
| `showSeconds` | `get showSeconds(): boolean;` | Read and write |
| `mask` | `get mask(): string;` | Read-only |
| `value` — Canonical YYYY-MM-DD or YYYY-MM-DDTHH:mm[:ss]; empty while incomplete/invalid. | `get value(): string;` | Read and write |
| `text` — Display text, including an incomplete or invalid draft. | `get text(): string;` | Read and write |
| `date` — A fresh Date at the start of the local day; null for an empty/incomplete/impossible date. | `get date(): Date \| null;` | Read and write |
| `datetime` — A fresh local Date including time; date mode returns the start of the local day. | `get datetime(): Date \| null;` | Read and write |
| `min` | `get min(): string;` | Read and write |
| `max` | `get max(): string;` | Read and write |
| `required` | `get required(): boolean;` | Read and write |
| `readOnly` | `get readOnly(): boolean;` | Read and write |
| `placeholder` | `get placeholder(): string;` | Read and write |
| `accessibleLabel` | `get accessibleLabel(): string;` | Read and write |
| `showCalendar` | `get showCalendar(): boolean;` | Read and write |
| `visible` | `get visible(): boolean;` | Read and write |
| `enabled` | `get enabled(): boolean;` | Read and write |
| `tabIndex` | `get tabIndex(): number;` | Read and write |
| `valid` | `get valid(): boolean;` | Read-only |
| `validationMessage` | `get validationMessage(): string;` | Read-only |
| `onChange` | `set onChange(handler: WebComponentEventHandler<this> \| null);` | Read and write |
| `onInput` | `set onInput(handler: WebComponentEventHandler<this> \| null);` | Read and write |

### `focus`

method

```ts
focus(options?: FocusOptions): void;
```

Example

```ts
Date1.focus({ preventScroll: true });
```

### `checkValidity`

method

```ts
checkValidity(): boolean;
```

Example

```ts
Date1.checkValidity();
```

### `reportValidity`

method

```ts
reportValidity(): boolean;
```

Example

```ts
Date1.reportValidity();
```

### `clear`

method

```ts
clear(): void;
```

Example

```ts
Date1.clear();
```

### `setNow`

method

```ts
setNow(): void;
```

Example

```ts
Date1.setNow();
```

### `showPicker`

method

```ts
showPicker(): boolean;
```

Opens the calendar aligned to the field, with a minimum popup width of 260px.

Example

```ts
Date1.showPicker();
```

### `dispose`

method

```ts
dispose(): void;
```

Example

```ts
// Call only when disposing of an instance whose lifecycle you control.
Date1.dispose();
```

Inherited members (22)

| Member | Signature | Access |
| --- | --- | --- |
| `currentRowBindings` | `currentRowBindings: readonly WebCurrentRowBinding[];` | Read and write |
| `element` | `readonly element: TElement;` | Read-only |
| `id` | `readonly id: string;` | Read-only |
| `name` | `readonly name: string;` | Read-only |
| `collapseWhenHidden` | `collapseWhenHidden: boolean;` | Read and write |
| `x` | `x: number;` | Read and write |
| `y` | `y: number;` | Read and write |
| `width` | `width: number;` | Read and write |
| `height` | `height: number;` | Read and write |
| `margin` — Outer spacing on all four sides, in pixels. | `margin: number;` | Read and write |
| `marginTop` | `marginTop: number;` | Read and write |
| `marginRight` | `marginRight: number;` | Read and write |
| `marginBottom` | `marginBottom: number;` | Read and write |
| `marginLeft` | `marginLeft: number;` | Read and write |
| `alignSelf` | `alignSelf: RuntimeLayoutAlignSelf;` | Read and write |
| `backgroundColor` | `backgroundColor: string;` | Read and write |
| `color` | `color: string;` | Read and write |
| `borderColor` | `borderColor: string;` | Read and write |

### `show`

method

```ts
show(): void;
```

### `hide`

method

```ts
hide(): void;
```

### `bindEvent`

method

```ts
bindEvent(eventName: string, handler: WebComponentEventHandler<this> | null): () => void;
```

### `emit`

method

```ts
emit(eventName: string, detail?: unknown): boolean;
```

## Events

Link methods in **Interaction**. [How to use events](https://webrad.atentor.com/docs/interactions).

### OnChange

Standard event (Event).

Signature and example

```ts
import type { WebDate } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Date1Change(
    sender: WebDate,
    event: Event,
  ): Promise<void> {
    console.log(sender.name, event.type);
  }
}
```

### OnInput

Standard event (Event).

Signature and example

```ts
import type { WebDate } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Date1Input(
    sender: WebDate,
    event: Event,
  ): Promise<void> {
    console.log(sender.name, event.type);
  }
}
```

### OnFocus

Standard event (Event).

Signature and example

```ts
import type { WebDate } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Date1Focus(
    sender: WebDate,
    event: Event,
  ): Promise<void> {
    console.log(sender.name, event.type);
  }
}
```

### OnBlur

Standard event (Event).

Signature and example

```ts
import type { WebDate } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Date1Blur(
    sender: WebDate,
    event: Event,
  ): Promise<void> {
    console.log(sender.name, event.type);
  }
}
```

### OnKeyDown

Standard event (Event).

Signature and example

```ts
import type { WebDate } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Date1KeyDown(
    sender: WebDate,
    event: Event,
  ): Promise<void> {
    if (event instanceof KeyboardEvent) console.log(event.key);
  }
}
```

### OnKeyUp

Standard event (Event).

Signature and example

```ts
import type { WebDate } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Date1KeyUp(
    sender: WebDate,
    event: Event,
  ): Promise<void> {
    if (event instanceof KeyboardEvent) console.log(event.key);
  }
}
```