DatePicker

See also

Material Design spec, Date picker

Date pickers let people select a date, or a range of dates.

• Date pickers can display past, present, or future dates

• Three types: docked, modal, modal input

• Clearly indicate important dates, such as current and selected days

• Follow common patterns, like a calendar view

1. Docked date picker

2. Modal date picker

3. Modal date input

KivyMD provides the following date pickers classes for use:

• MDDockedDatePicker

• MDModalDatePicker

• MDModalInputDatePicker

MDDockedDatePicker

Docked datepickers allow the selection of a specific date and year. The docked datepicker displays a date input field by default, and a dropdown calendar appears when the user taps on the input field. Either form of date entry can be interacted with.

Docked date pickers are ideal for navigating dates in both the near future or past and the distant future or past, as they provide multiple ways to select dates.

from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.pickers import MDDockedDatePicker

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDTextField:
        id: field
        mode: "outlined"
        pos_hint: {'center_x': .5, 'center_y': .85}
        size_hint_x: .5
        on_focus: app.show_date_picker(self.focus)

        MDTextFieldHintText:
            text: "Docked date picker"

        MDTextFieldHelperText:
            text: "MM/DD/YYYY"
            mode: "persistent"

        MDTextFieldTrailingIcon:
            icon: "calendar"
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)

    def show_date_picker(self, focus):
        if not focus:
            return

        date_dialog = MDDockedDatePicker()
        # You have to control the position of the date picker dialog yourself.
        date_dialog.pos = [
            self.root.ids.field.center_x - date_dialog.width / 2,
            self.root.ids.field.y - (date_dialog.height + dp(32)),
        ]
        date_dialog.open()


Example().run()

MDModalDatePicker

Modal date pickers navigate across dates in several ways:

• To navigate across months, swipe horizontally (not implemented in KivyMD)

• To navigate across years, scroll vertically (not implemented in KivyMD)

• To access the year picker, tap the year

Don’t use a modal date picker to prompt for dates in the distant past or future, such as a date of birth. In these cases, use a modal input picker or a docked datepicker instead.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.pickers import MDModalDatePicker

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release: app.show_date_picker()

        MDButtonText:
            text: "Open modal date picker dialog"
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)

    def show_date_picker(self):
        date_dialog = MDModalDatePicker()
        date_dialog.open()


Example().run()

MDModalInputDatePicker

Modal date inputs allow the manual entry of dates using the numbers on a keyboard. Users can input a date or a range of dates in a dialog.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.pickers import MDModalInputDatePicker

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release: app.show_date_picker()

        MDButtonText:
            text: "Open modal date picker dialog"
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)

    def show_date_picker(self):
        date_dialog = MDModalInputDatePicker()
        date_dialog.open()


Example().run()

The range of available dates

To display only the selected date range, use the min_date and max_date parameters:

def show_modal_date_picker(self, *args):
    MDModalDatePicker(
        mark_today=False,
        min_date=datetime.date.today(),
        max_date=datetime.date(
            datetime.date.today().year,
            datetime.date.today().month,
            datetime.date.today().day + 4,
        ),
    ).open()

Only dates in the specified range will be available for selection:

Select the date range

To select the date range, use the mode parameter with the value “range”:

def show_modal_date_picker(self, *args):
    MDModalDatePicker(mode="range").open()

Setting the date range manually

def show_modal_date_picker(self, *args):
    MDModalInputDatePicker(mode="range").open()

Events

on_edit event

from kivy.clock import Clock
from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.pickers import MDModalInputDatePicker, MDModalDatePicker

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release: app.show_modal_date_picker()

        MDButtonText:
            text: "Open modal date picker dialog"
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)

    def show_modal_input_date_picker(self, *args):
        def on_edit(*args):
            date_dialog.dismiss()
            Clock.schedule_once(self.show_modal_date_picker, 0.2)

        date_dialog = MDModalInputDatePicker()
        date_dialog.bind(on_edit=on_edit)
        date_dialog.open()

    def on_edit(self, instance_date_picker):
        instance_date_picker.dismiss()
        Clock.schedule_once(self.show_modal_input_date_picker, 0.2)

    def show_modal_date_picker(self, *args):
        date_dialog = MDModalDatePicker()
        date_dialog.bind(on_edit=self.on_edit)
        date_dialog.open()


Example().run()

on_select_day event

from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.pickers import MDModalDatePicker
from kivymd.uix.snackbar import MDSnackbar, MDSnackbarSupportingText

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release: app.show_modal_date_picker()

        MDButtonText:
            text: "Open modal date picker dialog"
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)

    def on_select_day(self, instance_date_picker, number_day):
        instance_date_picker.dismiss()
        MDSnackbar(
            MDSnackbarSupportingText(
                text=f"The selected day is {number_day}",
            ),
            y=dp(24),
            orientation="horizontal",
            pos_hint={"center_x": 0.5},
            size_hint_x=0.5,
            background_color="olive"
        ).open()

    def show_modal_date_picker(self, *args):
        date_dialog = MDModalDatePicker()
        date_dialog.bind(on_select_day=self.on_select_day)
        date_dialog.open()


Example().run()

on_select_month event

def on_select_month(self, instance_date_picker, number_month):
    [...]

def show_modal_date_picker(self, *args):
    [...]
    date_dialog.bind(on_select_month=self.on_select_month)
    [...]

on_select_year event

def on_select_year(self, instance_date_picker, number_year):
    [...]

def show_modal_date_picker(self, *args):
    [...]
    date_dialog.bind(on_select_month=self.on_select_year)
    [...]

on_cancel event

def on_cancel(self, instance_date_picker):
    [...]

def show_modal_date_picker(self, *args):
    [...]
    date_dialog.bind(on_cancel=self.on_cancel)
    [...]

on_ok event

def on_ok(self, instance_date_picker):
    print(instance_date_picker.get_date()[0])

def show_modal_date_picker(self, *args):
    [...]
    date_dialog.bind(on_ok=self.on_ok)
    [...]

on_ok with range event

import datetime

from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.pickers import MDModalDatePicker
from kivymd.uix.snackbar import (
    MDSnackbar, MDSnackbarSupportingText, MDSnackbarText
)

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release: app.show_modal_date_picker()

        MDButtonText:
            text: "Open modal date picker dialog"
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)

    def on_ok(self, instance_date_picker):
        MDSnackbar(
            MDSnackbarText(
                text="Selected dates is:",
            ),
            MDSnackbarSupportingText(
                text="\n".join(str(date) for date in instance_date_picker.get_date()),
                padding=[0, 0, 0, dp(12)],
            ),
            y=dp(124),
            pos_hint={"center_x": 0.5},
            size_hint_x=0.5,
            padding=[0, 0, "8dp", "8dp"],
        ).open()

    def show_modal_date_picker(self, *args):
        date_dialog = MDModalDatePicker(
            mode="range",
            min_date=datetime.date.today(),
            max_date=datetime.date(
                datetime.date.today().year,
                datetime.date.today().month,
                datetime.date.today().day + 4,
            ),
        )
        date_dialog.bind(on_ok=self.on_ok)
        date_dialog.open()


Example().run()

API break

1.2.0 version

date_dialog = MDDatePicker()
date_dialog.open()

2.0.0 version

# date_dialog = MDModalDatePicker()
# date_dialog = MDModalInputDatePicker()

date_dialog = MDDockedDatePicker()
date_dialog.open()

API - kivymd.uix.pickers.datepicker.datepicker

class kivymd.uix.pickers.datepicker.datepicker.MDBaseDatePicker(year=None, month=None, day=None, firstweekday=0, **kwargs)

Implements the base class of the date picker.

Added in version 2.0.0.

For more information, see in the ThemableBehavior and MotionDatePickerBehavior and BoxLayout and classes documentation.

Events:

on_select_day

Fired when a day is selected.

on_select_month

Fired when a month is selected.

on_select_year

Fired when a year is selected.

on_cancel

Fired when the ‘Cancel’ button is pressed.

on_ok

Fired when the ‘Ok’ button is pressed.

on_edit

Fired when you click on the date editing icon.

on_dismiss

Fired when a date picker closes.

day

The day of the month to be opened by default. If not specified, the current number will be used.

day is an NumericProperty and defaults to 0.

month

The number of month to be opened by default. If not specified, the current number will be used.

month is an NumericProperty and defaults to 0.

year

The year of month to be opened by default. If not specified, the current number will be used.

year is an NumericProperty and defaults to 0.

min_year

The year of month to be opened by default. If not specified, the current number will be used.

min_year is an NumericProperty and defaults to 1914.

max_year

The year of month to be opened by default. If not specified, the current number will be used.

max_year is an NumericProperty and defaults to 2121.

mode

Dialog type. Available options are: ‘picker’, ‘range’.

mode is an OptionProperty and defaults to picker.

min_date

The minimum value of the date range for the ‘mode’ parameter. Must be an object <class ‘datetime.date’>.

min_date is an ObjectProperty and defaults to None.

max_date

The minimum value of the date range for the ‘mode’ parameter. Must be an object <class ‘datetime.date’>.

max_date is an ObjectProperty and defaults to None.

radius

Container radius.

radius is an VariableListProperty and defaults to [dp(16), dp(16), dp(16), dp(16)].

scrim_color

Color for scrim in (r, g, b, a) or string format.

scrim_color is a ColorProperty and defaults to [0, 0, 0, 0.5].

supporting_text

Supporting text.

supporting_text is a StringProperty and defaults to ‘Select date’.

text_button_ok

The text of the confirmation button.

text_button_ok is a StringProperty and defaults to ‘Ok’.

text_button_cancel

The text of the cancel button.

text_button_cancel is a StringProperty and defaults to ‘Cancel’.

mark_today

Highlights the current day.

mark_today is a BooleanProperty and defaults to True.

is_open

Is the date picker dialog open.

is_open is a BooleanProperty and defaults to False.

sel_year

sel_month

sel_day

calendar_layout

get_date(*args) → list

Returns a list of dates in the format [datetime.date(yyyy, mm, dd), …]. The list has two dates if you use a date interval.

set_text_full_date() → str

Returns a string like “Tue, Feb 2”.

compare_date_range() → None

change_month(operation: str) → None

Called when “chevron-left” and “chevron-right” buttons are pressed. Switches the calendar to the previous/next month.

generate_list_widgets_days() → None

update_calendar(year, month) → None

set_selected_widget(widget) → None

restore_calendar_layout_properties() → None

set_calendar_layout_properties(method) → None

dismiss(*args) → None

Dismiss the dialog date picker.

open() → None

Show the dialog date picker.

on_touch_down(touch)

Receive a touch down event.

Parameters:

touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

on_select_day(*args) → None

Fired when a day is selected.

on_select_month(*args) → None

Fired when a month is selected.

on_select_year(*args) → None

Fired when a year is selected.

on_cancel(*args) → None

Fired when the ‘Cancel’ button is pressed.

on_ok(*args) → None

Fired when the ‘Ok’ button is pressed.

on_edit(*args) → None

Fired when you click on the date editing icon.

on_dismiss(*args) → None

Fired when a date picker closes.

class kivymd.uix.pickers.datepicker.datepicker.MDDockedDatePicker(**kwargs)

Implements docked date picker.

Added in version 2.0.0.

For more information, see in the CommonElevationBehavior and MDBaseDatePicker classes documentation.

generate_menu_month_year_selection(menu_type: str = 'month') → None

Generates a list for the month or year selection menu.

open_close_menu_month_year_selection(state: bool = True, menu_type: str = 'month') → None

Hides the calendar layout and opens the list to select the month or year.

class kivymd.uix.pickers.datepicker.datepicker.MDModalDatePicker(**kwargs)

Implements modal date picker.

Added in version 2.0.0.

For more information, see in the CommonElevationBehavior and MDBaseDatePicker classes documentation.

open() → None

Show the dialog date picker.

generate_list_widgets_years() → None

open_menu_year_selection(*args) → None

class kivymd.uix.pickers.datepicker.datepicker.MDModalInputDatePicker(*args, **kwargs)

Implements modal input date picker.

Added in version 2.0.0.

For more information, see in the CommonElevationBehavior and MDBaseDatePicker classes documentation.

date_format

Format of date strings that will be entered. Available options are: ‘dd/mm/yyyy’, ‘mm/dd/yyyy’, ‘yyyy/mm/dd’.

date_format is an OptionProperty and defaults to None.

default_input_date

If true, the current date will be set in the input field.

default_input_date is a BooleanProperty and defaults to True.

error_text

Error text when the date entered by the user is not valid.

error_text is a StringProperty and defaults to ‘Invalid date format’.

supporting_input_text

Auxiliary text when entering the date manually.

supporting_input_text is a StringProperty and defaults to ‘Enter date’.

generate_list_widgets_days() → None

update_calendar(*args) → None

set_input_date(input_date: str) → None

get_date(*args) → list

Returns a list of dates in the format [datetime.date(yyyy, mm, dd), …]. The list has two dates if you use a date interval.

get_current_date_from_format() → str

Returns the date according to the set format in date_format.

open() → None

Show the dialog date picker.