Skip to content

Latest commit

 

History

History
229 lines (190 loc) · 58.4 KB

datepicker.md

File metadata and controls

229 lines (190 loc) · 58.4 KB
Raw

DatePicker

DatePicker component provides a way to select a date using DateField & Calendar component. It follows the Native Input Date for the keyboard navigation & accessibility features. Supports all the features as React Aria's useDatePicker.

Table of Contents

Usage

import React from "react";

import CalendarBasic from "./CalendarBasic.component";
import DateFieldBasic from "./DateFieldBasic.component";
import {
  DatePickerDisclosure,
  DatePickerGroup,
  DatePickerLabel,
  DatePickerPopover,
  useDatePickerBaseState,
  useDatePickerState,
} from "@adaptui/react";

import { CalendarIcon } from "./Utils.component";

export const DatePickerBasic = props => {
  const state = useDatePickerBaseState({ ...props, gutter: 10 });
  const datepicker = useDatePickerState({ ...props, state });

  return (
    <div className="datepicker">
      <DatePickerLabel state={datepicker} className="datepicker__label">
        {props.label}
      </DatePickerLabel>
      <DatePickerGroup state={datepicker} className="datepicker__group">
        <DateFieldBasic {...datepicker.fieldProps} />
        <DatePickerDisclosure
          state={datepicker}
          className="datepicker__trigger"
        >
          <CalendarIcon />
        </DatePickerDisclosure>
      </DatePickerGroup>
      {state.popover.open && (
        <DatePickerPopover state={datepicker} className="popover">
          <CalendarBasic {...datepicker.calendarProps} />
        </DatePickerPopover>
      )}
    </div>
  );
};

export default DatePickerBasic;

Edit CodeSandbox Edit CodeSandbox

Other Examples

Edit CodeSandbox Edit CodeSandbox

Composition

  • useDatePickerBaseState uses useDatePickerState and usePopoverState
  • DatePickerDisclosure uses usePopoverDisclosure
  • DatePickerGroup uses Role
  • DatePickerLabel uses Role
  • DatePickerPopover uses usePopover
  • useDatePickerState uses its own state

Props

DatePickerBaseStateProps

DatePickerStateProps props > These props are returned by the other props You can also provide these props.
Name Type Description
shouldCloseOnSelect boolean | (() => boolean) | undefined Determines whether the date picker popover should close automatically when a date is selected.
minValue DateValue | undefined The minimum allowed date that a user may select.
maxValue DateValue | undefined The maximum allowed date that a user may select.
isDateUnavailable ((date: DateValue) => boolean) | undefined Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
placeholderValue T | undefined A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today's date at midnight.
hourCycle 12 | 24 | undefined Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
granularity Granularity | undefined Determines the smallest unit that is displayed in the date picker. By default, this is "day" for dates, and "minute" for times.
hideTimeZone boolean | undefined Whether to hide the time zone abbreviation.
isDisabled boolean | undefined Whether the input is disabled.
isReadOnly boolean | undefined Whether the input can be selected but not changed by the user.
validationState ValidationState | undefined Whether the input should display its "valid" or "invalid" visual styling.
isRequired boolean | undefined Whether user input is required on the input before form submission.Often paired with the necessityIndicator prop to add a visual indicator to the input.
autoFocus boolean | undefined Whether the element should receive focus on render.
onFocus ((e: FocusEvent<Element, Element>) => void) | u... Handler that is called when the element receives focus.
onBlur ((e: FocusEvent<Element, Element>) => void) | u... Handler that is called when the element loses focus.
onFocusChange ((isFocused: boolean) => void) | undefined Handler that is called when the element's focus status changes.
onKeyDown ((e: KeyboardEvent) => void) | undefined Handler that is called when a key is pressed.
onKeyUp ((e: KeyboardEvent) => void) | undefined Handler that is called when a key is released.
label ReactNode The content to display as the label.
description ReactNode A description for the field. Provides a hint such as specific requirements for what to choose.
errorMessage ReactNode An error message for the field.
isOpen boolean | undefined Whether the overlay is open by default (controlled).
defaultOpen boolean | undefined Whether the overlay is open by default (uncontrolled).
onOpenChange ((isOpen: boolean) => void) | undefined Handler that is called when the overlay's open state changes.
value T | undefined The current value (controlled).
defaultValue T | undefined The default value (uncontrolled).
onChange ((value: C) => void) | undefined Handler that is called when the value changes.
PopoverStateProps props > These props are returned by the other props You can also provide these props.
Name Type Description
defaultOpen boolean | undefined Whether the overlay is open by default (uncontrolled).
open boolean The visibility state of the content.
animated number | boolean Determines whether the content should animate when it is shown or hidden. - If true, the animating state will be true when the content is shown or hidden and it will wait for stopAnimation to be called or a CSS animation/transition to end before becoming false. - If it's set to a number, the animating state will be true when the content is shown or hidden and it will wait for the number of milliseconds to pass before becoming false.
setOpen ((open: boolean) => void) | undefined Function that will be called when setting the disclosure open state.
getAnchorRect (anchor: HTMLElement | null) => AnchorRect | null Function that returns the anchor element's DOMRect. If this is explicitlypassed, it will override the anchor getBoundingClientRect method.
placement Placement The placement of the popover.
fixed boolean Whether the popover has position: fixed or not.
gutter number | undefined The distance between the popover and the anchor element. By default, it's 0plus half of the arrow offset, if it exists.
shift number The skidding of the popover along the anchor element.
flip string | boolean Controls the behavior of the popover when it overflows the viewport: - If a boolean, specifies whether the popover should flip to the opposite side when it overflows. - If a string, indicates the preferred fallback placements when it overflows. The placements must be spaced-delimited, e.g. "top left".
slide boolean Whether the popover should slide when it overflows.
overlap boolean Whether the popover can overlap the anchor element when it overflows.
sameWidth boolean Whether the popover should have the same width as the anchor element. Thiswill be exposed to CSS as --popover-anchor-width.
fitViewport boolean Whether the popover should fit the viewport. If this is set to true, thepopover wrapper will have maxWidth and maxHeight set to the viewportsize. This will be exposed to CSS as --popover-available-width and--popover-available-height.
arrowPadding number The minimum padding between the arrow and the popover corner.
overflowPadding number The minimum padding between the popover and the viewport edge. This will beexposed to CSS as --popover-overflow-padding.
renderCallback ((props: PopoverStateRenderCallbackProps) => vo... A function that will be called when the popover needs to calculate itsstyles. It will override the internal behavior.

DatePickerDisclosureOptions

Name Type Description
state DatePickerState | DateRangePickerState Object returned by the useDatePickerState & useDateRangePickerState hook.
PopoverDisclosureOptions props > These props are returned by the other props You can also provide these props.
Name Type Description
disabled boolean | undefined Determines whether the focusable element is disabled. If the focusableelement doesn't support the native disabled attribute, thearia-disabled attribute will be used instead.
autoFocus boolean | undefined Automatically focus the element when it is mounted. It works similarly tothe native autoFocus prop, but solves an issue where the element isgiven focus before React effects can run.
focusable boolean | undefined Whether the element should be focusable.
accessibleWhenDisabled boolean | undefined Determines whether the element should be focusable even when it isdisabled.This is important when discoverability is a concern. For example:> A toolbar in an editor contains a set of special smart paste functionsthat are disabled when the clipboard is empty or when the function is notapplicable to the current content of the clipboard. It could be helpful tokeep the disabled buttons focusable if the ability to discover theirfunctionality is primarily via their presence on the toolbar.Learn more on Focusability of disabledcontrols.
onFocusVisible ((event: SyntheticEvent<Element, Event>) => voi... Custom event handler that is called when the element is focused via thekeyboard or when a key is pressed while the element is focused.
clickOnEnter boolean | undefined If true, pressing the enter key will trigger a click on the button.
clickOnSpace boolean | undefined If true, pressing the space key will trigger a click on the button.
toggleOnClick BooleanOrCallback<MouseEvent<HTMLElement, Mouse... Determines whether state.toggle() will be called on click. This is usefulif you want to handle the toggle logic yourself.

DatePickerGroupOptions

Name Type Description
state DatePickerState | DateRangePickerState Object returned by the useDatePickerState & useDateRangePickerState hook.

DatePickerLabelOptions

Name Type Description
state DatePickerState | DateRangePickerState Object returned by the useDatePickerState & useDateRangePickerState hook.

DatePickerPopoverOptions

Name Type Description
state DatePickerState | DateRangePickerState Object returned by the useDatePickerState & useDateRangePickerState hook.
PopoverOptions props > These props are returned by the other props You can also provide these props.
Name Type Description
disabled boolean | undefined Determines whether the focusable element is disabled. If the focusableelement doesn't support the native disabled attribute, thearia-disabled attribute will be used instead.
autoFocus boolean | undefined Automatically focus the element when it is mounted. It works similarly tothe native autoFocus prop, but solves an issue where the element isgiven focus before React effects can run.
focusable boolean | undefined Whether the element should be focusable.
accessibleWhenDisabled boolean | undefined Determines whether the element should be focusable even when it isdisabled.This is important when discoverability is a concern. For example:> A toolbar in an editor contains a set of special smart paste functionsthat are disabled when the clipboard is empty or when the function is notapplicable to the current content of the clipboard. It could be helpful tokeep the disabled buttons focusable if the ability to discover theirfunctionality is primarily via their presence on the toolbar.Learn more on Focusability of disabledcontrols.
onFocusVisible ((event: SyntheticEvent<Element, Event>) => voi... Custom event handler that is called when the element is focused via thekeyboard or when a key is pressed while the element is focused.
preserveTabOrder boolean | undefined When enabled, preserveTabOrder will keep the DOM element's tab order thesame as the order in which the Portal component was mounted in the Reacttree.
portalRef ((instance: HTMLElement | null) => void) | Muta... portalRef is similar to ref but is scoped to the portal node. It'suseful when you need to be informed when the portal element is appended tothe DOM or removed from the DOM.
portal boolean | undefined Determines whether the element should be rendered as a React Portal.
portalElement HTMLElement | ((element: HTMLElement) => HTMLEl... An HTML element or a memoized callback function that returns an HTMLelement to be used as the portal element. By default, the portal elementwill be a div element appended to the document.body.
modal boolean | undefined Determines whether the dialog is modal. Modal dialogs have distinctstates and behaviors: - The portal, backdrop and preventBodyScroll props are set to true. They can still be manually set to false. - A visually hidden dismiss button will be rendered if the DialogDismiss component hasn't been used. This allows screen reader users to close the dialog. - The focus will be trapped within the dialog. - When the dialog is open, the elements outside of the dialog will be hidden to assistive technology users using the aria-hidden attribute. - When using the Heading or DialogHeading components within the dialog, their level will be reset so they start with h1.
backdrop boolean | ElementType<Pick<DetailedHTMLProps<HT... Determines whether there will be a backdrop behind the dialog. On modaldialogs, this is true by default. Besides a boolean, this prop canalso be a React component that will be rendered as the backdrop.
backdropProps Omit<DisclosureContentProps<"div">, "state"> | ... Props that will be passed to the backdrop element if backdrop istrue.
hideOnEscape BooleanOrCallback<KeyboardEvent | React.Keyboar... Determines whether the dialog will be hidden when the user presses theEscape key.
hideOnInteractOutside BooleanOrCallback<Event | SyntheticEvent<Elemen... Determines whether the dialog will be hidden when the user clicks orfocus on an element outside of the dialog.
preventBodyScroll boolean | undefined Determines whether the body scrolling will be prevented when the dialogis shown.
autoFocusOnShow BooleanOrCallback<HTMLElement> | undefined Determines whether an element inside the dialog will receive focus whenthe dialog is shown. By default, this is usually the first tabbableelement in the dialog or the dialog itself. The initialFocusRef propcan be used to set a different element to receive focus.
autoFocusOnHide BooleanOrCallback<HTMLElement> | undefined Determines whether an element outside of the dialog will be focused whenthe dialog is hidden if another element hasn't been focused in the actionof hiding the dialog (for example, by clicking or tabbing into anothertabbable element outside of the dialog). By default, this is usually thedisclosure element. The finalFocusRef prop can be used to define adifferent element to be focused.
initialFocusRef RefObject<HTMLElement> | undefined Determines which element will receive focus when the dialog is shown.This has no effect if autoFocusOnShow is false. If not set, the firsttabbable element inside the dialog or the dialog itself will receivefocus.
finalFocusRef RefObject<HTMLElement> | undefined Determines which element will receive focus when the dialog is hidden ifanother element hasn't been focused in the action of hiding the dialog(for example, by clicking or tabbing into another tabbable elementoutside of the dialog). This has no effect if autoFocusOnHide isfalse. If not set, the disclosure element will be used.
wrapperProps HTMLAttributes<HTMLDivElement> | undefined Props that will be passed to the popover wrapper element. This element willbe used to position the popover.

DatePickerStateProps

Name Type Description
aria-label string | undefined Defines a string value that labels the current element.
aria-labelledby string | undefined Identifies the element (or elements) that labels the current element.
aria-describedby string | undefined Identifies the element (or elements) that describes the object.
aria-details string | undefined Identifies the element (or elements) that provide a detailed, extended description for the object.
id string | undefined The element's unique identifier. See MDN.
state DatePickerBaseState Object returned by the useDatePickerBaseState hook.