> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Date Field Single – Design
> A form field for selecting a single date with calendar picker support.
export const DoDont = ({text, type, children}) => {
return <>
{type === "do" &&
## Anatomy
Date Field Single consists of five primary elements that enable users to select a single date through text input or a calendar picker.
1. **Label** - Identifies the field and its purpose
2. **Input field** - Text input for manual date entry with format mask
3. **Helper text** (Optional) - Description, format hint or error message
## Options
Date Field Single supports the following configurations to accommodate different use cases and regional preferences.
### Date Format Modes
```tsx lines theme={null}
import { DateFieldSingle, Flex } from "@servicetitan/anvil2";
function App() {
return (
{/** US format (default) */}
{/** International format */}
);
}
export default App;
```
Date Field Single supports two date format modes to match regional conventions. The default format is `mm/dd/yyyy` for US audiences, while `dd/mm/yyyy` is available for international users.
| Mode | Format | Use Case |
| ---------- | -------- | ------------------------- |
| mm/dd/yyyy | Default | US date format |
| dd/mm/yyyy | Optional | International date format |
### Sizes
```tsx lines theme={null}
import { DateFieldSingle, Flex } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
Three size options accommodate different layout densities and visual hierarchies.
| Size | Height |
| ------ | ------ |
| Small | 32px |
| Medium | 40px |
| Large | 48px |
### Calendar Picker
```tsx lines theme={null}
import { DateFieldSingle } from "@servicetitan/anvil2";
function App() {
return ;
}
export default App;
```
The calendar picker can be disabled when manual text entry is preferred or when the calendar interface is not suitable for the use case.
## Behavior
Date Field Single responds to user interaction with distinct visual states and validation feedback.
### Visual States
```tsx lines theme={null}
import { DateFieldSingle, Grid } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
The component displays different visual states to communicate field status and interactivity. Default state shows the field ready for input. Focus state highlights the active field. Error state displays validation messages when dates are invalid or required fields are empty. Disabled state prevents interaction while maintaining visual context.
### Calendar Interaction
Clicking the input field opens a popover calendar. Users can navigate months and select dates directly from the calendar. The calendar closes automatically after selection, and the selected date populates the input field.
### Validation
```tsx lines theme={null}
import {
DateFieldSingle,
Flex,
type DateFieldSingleChange,
} from "@servicetitan/anvil2";
import { useState } from "react";
function App() {
const [value, setValue] = useState();
const [latestEvent, setLatestEvent] = useState();
const [errorMessage, setErrorMessage] = useState("");
const handleChange = (change: DateFieldSingleChange) => {
setValue(change.date);
setLatestEvent(change);
if (change.isDateValid) setErrorMessage("");
};
const handleBlur = () => {
if (!latestEvent) return;
if (!latestEvent.isDateValid) return setErrorMessage("Invalid date");
if (!latestEvent.isInputValid && !latestEvent.isInputEmpty)
return setErrorMessage("Valid date, but input isn't fully filled");
};
return (
{JSON.stringify(latestEvent, null, 2)}
);
}
export default App;
```
Date Field Single validates input in real time. The component checks for parseable dates, required field completion, date constraints (min/max dates), and unavailable dates or days of the week. Error messages appear below the field when validation fails.
## Usage Guidelines
### When to Use
Use Date Field Single when you need to:
* Capture a single, specific date
* Provide calendar visual context for date selection
* Support both manual entry and visual selection
* Validate dates against constraints like minimum or maximum dates
### When not to use
Avoid using Date Field Single for:
* **Date ranges** - Use [Date Field Range](/docs/web/components/date-field-range/design) instead
* **Recurring dates without year** - Use [Date Field Yearless](/docs/web/components/date-field-yearless/design) for birthdays, anniversaries, or seasonal dates
* **Time selection** - Use [Time Field](/docs/web/components/time-field/design) for time-only inputs
### Alternatives
#### Date Field Single vs Date Field Yearless
Use Date Field Single when the year is essential to the date selection, such as appointment scheduling or deadline setting. Use Date Field Yearless when the year is irrelevant, such as recurring annual events or template dates.
### How to Use
#### Labeling and Context
Provide clear, descriptive labels that communicate the purpose of the date selection. Labels should indicate what the date represents and why it's needed. Use helper text or descriptions when additional context helps users understand constraints or requirements.
```tsx lines theme={null}
import { DateFieldSingle } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
* Write labels that clearly communicate the purpose of the date selection
* Include format hints to guide users on expected input format
* Set appropriate date constraints (min/max dates) to prevent invalid selections
* Display validation errors immediately when they occur
* Use the calendar picker to provide visual date selection when helpful
#### Anti-pattern: Ambiguous Context and Format
Avoid creating confusion by omitting format guidance or using Date Field Single for dates where year information is irrelevant.
```tsx lines theme={null}
import { DateFieldSingle } from "@servicetitan/anvil2";
function App() {
return ;
}
export default App;
```
* Use Date Field Single for recurring annual events where year doesn't matter
* Omit format hints when the date format might be ambiguous to users
* Hide validation errors until form submission
* Use placeholder text to communicate date format instead of format hints
* Create labels that don't clearly indicate what date is being selected
## Content
Content within Date Field Single should be clear, concise, and actionable.
* Labels should clearly indicate what date is being selected
* Error messages should explain why a date is invalid and how to fix it
* Format hints should match the selected mode (mm/dd/yyyy or dd/mm/yyyy)
* Descriptions should provide context without overwhelming the user
## Keyboard Interaction
Users can navigate Date Field Single using standard keyboard controls.
### Input Field
| Key | Description |
| ----------- | -------------------------------------- |
| Tab | Moves focus to the next element |
| Shift + Tab | Moves focus to the previous element |
| Arrow Down | Opens the calendar picker when focused |
| Esc | Closes the calendar picker |
### Calendar Picker
| Key | Description |
| ----------------- | ------------------------------------------------- |
| Arrow Left | Moves focus to the previous day |
| Arrow Right | Moves focus to the next day |
| Arrow Up | Moves focus to the same day in the previous week |
| Arrow Down | Moves focus to the same day in the next week |
| Page Up | Moves focus to the same day in the previous month |
| Page Down | Moves focus to the same day in the next month |
| Shift + Page Up | Moves focus to the same day in the previous year |
| Shift + Page Down | Moves focus to the same day in the next year |
| Enter | Selects the focused date |
| Space | Selects the focused date |
| Esc | Closes the calendar picker |
### Accessibility
Date Field Single includes built-in accessibility features. The component supports full keyboard navigation and screen reader compatibility. Ensure labels are descriptive and error messages are clear for assistive technology users.
For more guidance on form field labels and context, see [input field context association best practices](/docs/accessibility/labels-and-ctas#input-field-context-association).
