## TimePicker  
Use the TimeInput component to capture time input from user.  
Category: Date Pickers  

### Usage

`TimePicker` component is an alternative to [TimeInput](/components/timeinput) that offers more features, it supports 
24-hour and 12-hour formats, dropdown with hours, minutes and seconds, and more.

```python
import dash_mantine_components as dmc
from dash import callback, Input, Output


component = dmc.Group(
    gap=50,
    children=[
        dmc.TimePicker(label="Enter a time", id="timepicker-usage"),
        dmc.Text(id="out-timepicker")
    ],
)

@callback(
    Output("out-timepicker", "children"),
    Input("timepicker-usage", "value")
)
def update(value):
    return f"You entered: {value}"
```
### With callbacks

`TimePicker` component value is a string in hh:mm:ss 24-hour format (for example 18:34:55). Empty string is used to
represent no value. The `value` props is updated when the entered value is valid. The input value is considered valid
in the following cases:

- All inputs are empty. In this case the `value` will be  an empty string.
- All inputs are filled. For example if `withSeconds` prop is set and the user entered 12:34:56, the value will be
12:34:56. But if the user entered 12:34, `value` will not be updated because seconds value is missing.
- If a complete, valid time has been entered, the value will update as the user changes any part of it (hours, minutes,
or seconds). Each digit change will immediately reflect in the updated value.

### Debounce

To control how often the input's value is updated while the user is typing, use the `debounce` prop:

- Set `debounce=True` to update the value only when the user finishes typing and moves focus away (i.e. on blur).
- Set `debounce=<milliseconds>` to update the value after a specified delay from the user's last keystroke. For example,
`debounce=300` will wait 300 milliseconds after the user stops typing before updating the value.

#### Example debounce=True
```python
import dash_mantine_components as dmc
from dash import callback, Input, Output


component = dmc.Group(
    gap=50,
    children=[
        dmc.TimePicker(
            label="Enter a time",
            debounce=True,
            id="timepicker-debounce"
        ),
        dmc.Text(id="out-timepicker-debounce")
    ],
)

@callback(
    Output("out-timepicker-debounce", "children"),
    Input("timepicker-debounce", "value")
)
def update(value):
    return f"You entered: {value}"
```
#### Example debounce=1000
```python
import dash_mantine_components as dmc
from dash import callback, Input, Output


component = dmc.Group(
    gap=50,
    children=[
        dmc.TimePicker(
            label="Enter a time",
            debounce=1000,
            id="timepicker-debounce-ms"
        ),
        dmc.Text(id="out-timepicker-debounce-ms")
    ],
)

@callback(
    Output("out-timepicker-debounce-ms", "children"),
    Input("timepicker-debounce-ms", "value")
)
def update(value):
    return f"You entered: {value}"
```
### With seconds
Set `withSeconds` prop to enable seconds input. Note that if this prop is used, the value is not updated until all
inputs are filled – it is not possible to enter only hours and minutes.

```python
import dash_mantine_components as dmc
from dash import callback, Input, Output


component = dmc.Group(
    gap=50,
    children=[
        dmc.TimePicker(label="Enter a time", withSeconds=True, id="timepicker-seconds"),
        dmc.Text(id="out-timepicker-seconds")
    ],
)

@callback(
    Output("out-timepicker-seconds", "children"),
    Input("timepicker-seconds", "value")
)
def update(value):
    return f"You entered: {value}"
```
### 12-hour format
Set `format="12h"` to use 12-hour format. Note that `value` is updated only when all inputs are filled including am/pm input.


```python
import dash_mantine_components as dmc
from dash import callback, Input, Output


component = dmc.Group(
    gap=50,
    children=[
        dmc.TimePicker(label="Enter a time", format="12h", id="timepicker-12"),
        dmc.Text(id="out-timepicker-12")
    ],
)

@callback(
    Output("out-timepicker-12", "children"),
    Input("timepicker-12", "value")
)
def update(value):
    return f"You entered: {value}"
```
### Change am/pm labels
To change am/pm labels use `amPmLabels` prop. Example of changing labels to Hindi:


```python
import dash_mantine_components as dmc

component =  dmc.TimePicker(
    label="Enter a time",
    format="12h",
    amPmLabels={"am": 'पूर्वाह्न', "pm": 'अपराह्न'}
)
```
### Min and max values
Set `min` and `max` props to limit available time range:

```python
import dash_mantine_components as dmc

component =  dmc.TimePicker(
    label="Enter a time between 10:00 and 18:30",
    min="10:00",
    max="18:30"
)
```
### With dropdown
Set `withDropdown` prop to display the dropdown with hours, minutes, seconds and am/pm selects. By default,
the dropdown is visible when one of the inputs is focused.

```python
import dash_mantine_components as dmc


component = dmc.Group(
    gap=50,
    mb=60,
    children=[
        dmc.TimePicker(
            label="Enter time (24h format)",
            withSeconds=True,
            withDropdown=True
        ),
        dmc.TimePicker(
            label="Enter time (12h format)",
            withSeconds=True,
            withDropdown=True,
            format="12h"
        ),
    ],
)
```
### Hours/minutes/seconds step
Use `hoursStep`, `minutesStep` and `secondsStep` props to control step for each input. These props are used to control
value by which the input is incremented or decremented when up/down arrow keys are pressed and to generate corresponding
values range in the dropdown.

```python
import dash_mantine_components as dmc

component =  dmc.TimePicker(
    label="Enter a time",
    withSeconds=True,
    withDropdown=True,
    hoursStep=1,
    minutesStep=5,
    secondsStep=10
)
```
### Time presets
You can define time presets with `presets` prop. Presets are displayed in the dropdown and can be selected by clicking
on them. Time values for presets should be in hh:mm:ss or hh:mm 24-hour time format. Presets display value is generated
based on `format`, `amPmLabels` and `withSeconds` props.


```python
import dash_mantine_components as dmc
from dash import callback, Input, Output


component = dmc.TimePicker(
    label="Enter a time",
    format="12h",
    withDropdown=True,
    presets=['11:30', '15:45', '18:00', '20:15', '22:30']
)
```
### Time presets groups
To group presets use a list of dictionaries with label and values keys:


```python
import dash_mantine_components as dmc
from dash import callback, Input, Output


component = dmc.TimePicker(
    label="Enter a time",
    withDropdown=True,
    maxDropdownContentHeight=300,
    presets = [
        {"label": 'Morning', "values": ['06:00:00', '08:00:00', '10:00:00']},
        {"label": 'Afternoon', "values": ['12:00:00', '14:00:00', '16:00:00']},
        {"label": 'Evening', "values": ['18:00:00', '20:00:00', '22:00:00']},
    ],
    mb=120,
)
```
### Time presets range
Use the `timeRangePresets` prop to generate a range of times. It accepts a dictionary with `startTime`,
`endTime`, and `interval` keys, where all values are strings in `hh:mm:ss` format. This overrides any values provided 
directly in the `presets` prop.

```python
import dash_mantine_components as dmc
from dash import callback, Input, Output


component = dmc.TimePicker(
    label="Enter a time",
    format="12h",
    withDropdown=True,
    timeRangePresets={"startTime": "06:00:00", "endTime": "18:00:00", "interval": "01:30:00"}
)
```
### Dropdown position
By default, the dropdown is displayed below the input if there is enough space; otherwise it is displayed above the 
input. You can change this behavior by setting `position` and `middlewares` props, which are passed down to the
underlying `Popover` component.

Example of dropdown that is always displayed above the input:


```python
import dash_mantine_components as dmc
from dash import callback, Input, Output


component = dmc.TimePicker(
    label="Enter a time",
    withDropdown=True,
    popoverProps={
        "position": 'top-start',
        "middlewares": {"flip": False, "shift": False },
      }
)
```
### Dropdown width
To change dropdown width, set `width` prop in `popoverProps`. By default, dropdown width is adjusted to fit all content.
Example of dropdown width set to the input width:

```python
import dash_mantine_components as dmc
from dash import callback, Input, Output


component = dmc.TimePicker(
    label="Enter a time",
    withDropdown=True,
    withSeconds=True,
    format="12h",
    popoverProps={"width": "target"}
)
```
### Clearable
Set `clearable` prop to display a clear button in the right section of the input. The clear button is visible when at
least one of the fields has value.


```python
import dash_mantine_components as dmc
from dash import callback, Input, Output


component = dmc.TimePicker(
    label="Enter a time",
    withDropdown=True,
    withSeconds=True,
    clearable=True,
    value="12:30:00"
)
```
### Disabled

```python
import dash_mantine_components as dmc
from dash import callback, Input, Output


component = dmc.TimePicker(
    label="Enter a time",
    disabled=True
)
```
### Read only

```python
import dash_mantine_components as dmc
from dash import callback, Input, Output


component = dmc.TimePicker(
    label="Enter a time",
    readOnly=True,
    value="12:30:00"
)
```
### Input Props

TimeInput supports all props from Input and InputWrapper components such as `radius`, `size`, `required`, etc.

### Invalid State And Error

You can display an error with a red border and add an error message.

```python
import dash_mantine_components as dmc

component = dmc.Stack(
    children=[
        dmc.TimePicker(label="Enter Time:", w=100, error=True),
        dmc.TimePicker(
            label="Enter Time:",
            w=150,
            error="Enter a valid time",
            withSeconds=True,
        ),
    ],
)
```
### Accessibility

Set aria labels for hours, minutes, seconds and am/pm inputs and clear button with corresponding props:
```python
    dmc.TimePicker(
      hoursInputLabel="Hours",
      minutesInputLabel="Minutes",
      secondsInputLabel="Seconds",
      amPmInputLabel="AM/PM",
      clearButtonProps={{ 'aria-label': 'Clear time' }}
    
  )
```

### Keyboard Interactions


| Key          | Description                              |
| ------------ | ---------------------------------------- |
| `ArrowDown`  | Decrements current value by step         |
| `ArrowUp`    | Increments current value by step         |
| `Home`       | Sets current value to min possible value |
| `End`        | Sets current value to max possible value |
| `Backspace`  | Clears current value                     |
| `ArrowRight` | Moves focus to the next input            |
| `ArrowLeft`  | Moves focus to the previous input        |



### Styles API


This component supports Styles API. With Styles API, you can customize styles of any inner element. See the Styling and Theming sections of these docs for more information.
     


#### TimePicker Selectors

| Selector          | Static selector                         | Description                                                       |
| ----------------- | --------------------------------------- | ----------------------------------------------------------------- |
| wrapper           | `.mantine-TimePicker-wrapper`           | Root element of the Input                                         |
| input             | `.mantine-TimePicker-input`             | Input element                                                     |
| section           | `.mantine-TimePicker-section`           | Left and right sections                                           |
| root              | `.mantine-TimePicker-root`              | Root element                                                      |
| label             | `.mantine-TimePicker-label`             | Label element                                                     |
| required          | `.mantine-TimePicker-required`          | Required asterisk element, rendered inside label                  |
| description       | `.mantine-TimePicker-description`       | Description element                                               |
| error             | `.mantine-TimePicker-error`             | Error element                                                     |
| control           | `.mantine-TimePicker-control`           | Button in the dropdown used to select hours/minutes/seconds/am-pm |
| controlsList      | `.mantine-TimePicker-controlsList`      | List of buttons for hours/minutes/seconds/am-pm                   |
| controlsListGroup | `.mantine-TimePicker-controlsListGroup` | Group of `controlsList`s                                          |
| dropdown          | `.mantine-TimePicker-dropdown`          | Popover dropdown                                                  |
| fieldsRoot        | `.mantine-TimePicker-fieldsRoot`        | Wrapper for all `fieldsGroup` elements                            |
| fieldsGroup       | `.mantine-TimePicker-fieldsGroup`       | Wrapper for hours/minutes/seconds/am-pm fields                    |
| field             | `.mantine-TimePicker-field`             | Hours/minutes/seconds/am-pm input field                           |
| presetControl     | `.mantine-TimePicker-presetControl`     | Time preset button                                                |
| presetsGroup      | `.mantine-TimePicker-presetsGroup`      | Wraps preset controls and label                                   |
| presetsGroupLabel | `.mantine-TimePicker-presetsGroupLabel` | Label of the preset group                                         |
| presetsRoot       | `.mantine-TimePicker-presetsRoot`       | Wrapper for all presets content                                   |
| scrollarea        | `.mantine-TimePicker-scrollarea`        | Scroll area in the dropdown                                       |


#### TimePicker CSS Variables

| Selector | Variable              | Description                             |
| -------- | --------------------- | --------------------------------------- |
| dropdown | `--control-font-size` | Controls font-size of dropdown controls |



### Keyword Arguments
#### TimePicker

- id (string; optional):
    Unique ID to identify this component in Dash callbacks.

- amPmInputLabel (string; optional):
    `aria-label` of am/pm input.

- amPmLabels (dict; optional):
    Labels used for am/pm values, `{ am: 'AM', pm: 'PM' }` by default.

    `amPmLabels` is a dict with keys:

- amPmSelectProps (boolean | number | string | dict | list; optional):
    Props passed down to am/pm select.

- aria-* (string; optional):
    Wild card aria attributes.

- attributes (boolean | number | string | dict | list; optional):
    Passes attributes to inner elements of a component.  See Styles
    API docs.

- className (string; optional):
    Class added to the root element, if applicable.

- classNames (dict; optional):
    Adds custom CSS class names to inner elements of a component.  See
    Styles API docs.

- clearButtonProps (boolean | number | string | dict | list; optional):
    Props passed down to clear button.

- clearable (boolean; optional):
    Determines whether the clear button should be displayed, `False`
    by default.

- darkHidden (boolean; optional):
    Determines whether component should be hidden in dark color scheme
    with `display: none`.

- data-* (string; optional):
    Wild card data attributes.

- debounce (number | boolean; default False):
    (boolean | number; default False): If True, changes to input will
    be sent back to the Dash server only on enter or when losing
    focus. If it's False, it will send the value back on every change.
    If a number, it will not send anything back to the Dash server
    until the user has stopped typing for that number of milliseconds.

- defaultValue (string; optional):
    Uncontrolled component default value.

- description (a list of or a singular dash component, string or number; optional):
    Contents of `Input.Description` component. If not set, description
    is not rendered.

- descriptionProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional):
    Props passed down to the `Input.Description` component.

- disabled (boolean; optional):
    If set, the component becomes disabled.

- error (a list of or a singular dash component, string or number; optional):
    Contents of `Input.Error` component. If not set, error is not
    rendered.

- errorProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional):
    Props passed down to the `Input.Error` component.

- form (string; optional):
    `form` prop passed down to the hidden input.

- format (a value equal to: '12h', '24h'; optional):
    Time format, `'24h'` by default.

- hiddenFrom (string; optional):
    Breakpoint above which the component is hidden with `display:
    none`.

- hiddenInputProps (boolean | number | string | dict | list; optional):
    Props passed down to the hidden input.

- hoursInputLabel (string; optional):
    `aria-label` of hours input.

- hoursInputProps (boolean | number | string | dict | list; optional):
    Props passed down to hours input.

- hoursStep (number; optional):
    Number by which hours are incremented/decremented, `1` by default.

- inputProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional):
    Props passed down to the `Input` component.

- inputWrapperOrder (list of a value equal to: 'label', 'description', 'error', 'input's; optional):
    Controls order of the elements, `['label', 'description', 'input',
    'error']` by default.

- label (a list of or a singular dash component, string or number; optional):
    Contents of `Input.Label` component. If not set, label is not
    rendered.

- labelProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional):
    Props passed down to the `Input.Label` component.

- leftSection (a list of or a singular dash component, string or number; optional):
    Content section rendered on the left side of the input.

- leftSectionPointerEvents (a value equal to: '-moz-initial', 'inherit', 'initial', 'revert', 'revert-layer', 'unset', 'auto', 'none', 'all', 'fill', 'painted', 'stroke', 'visible', 'visibleFill', 'visiblePainted', 'visibleStroke'; optional):
    Sets `pointer-events` styles on the `leftSection` element,
    `'none'` by default.

- leftSectionProps (dict; optional):
    Props passed down to the `leftSection` element.

- leftSectionWidth (string | number; optional):
    Left section width, used to set `width` of the section and input
    `padding-left`, by default equals to the input height.

- lightHidden (boolean; optional):
    Determines whether component should be hidden in light color
    scheme with `display: none`.

- loading_state (dict; optional):
    Object that holds the loading state object coming from
    dash-renderer. For use with dash<3.

    `loading_state` is a dict with keys:

- max (string; optional):
    Max possible time value in `hh:mm:ss` format.

- maxDropdownContentHeight (number; optional):
    Maximum height of the content displayed in the dropdown in px,
    `200` by default.

- min (string; optional):
    Min possible time value in `hh:mm:ss` format.

- minutesInputLabel (string; optional):
    `aria-label` of minutes input.

- minutesInputProps (boolean | number | string | dict | list; optional):
    Props passed down to minutes input.

- minutesStep (number; optional):
    Number by which minutes are incremented/decremented, `1` by
    default.

- mod (string | dict | list of string | dicts; optional):
    Element modifiers transformed into `data-` attributes. For
    example: "xl" or {"data-size": "xl"}. Can also be a list of
    strings or dicts for multiple modifiers. Falsy values are removed.

- n_blur (number; default 0):
    An integer that represents the number of times that this element
    has lost focus.

- n_submit (number; default 0):
    An integer that represents the number of times that this element
    has been submitted.

- name (string; optional):
    `name` prop passed down to the hidden input.

- pasteSplit (dict; optional):
    A function to transform paste values, by default time in 24h
    format can be parsed on paste for example `23:34:22`.

    `pasteSplit` is a dict with keys:

- persisted_props (list of strings; optional):
    Properties whose user interactions will persist after refreshing
    the component or the page. Since only `value` is allowed this prop
    can normally be ignored.

- persistence (string | number | boolean; optional):
    Used to allow user interactions in this component to be persisted
    when the component - or the page - is refreshed. If `persisted` is
    truthy and hasn't changed from its previous value, a `value` that
    the user has changed while using the app will keep that change, as
    long as the new `value` also matches what was given originally.
    Used in conjunction with `persistence_type`. Note:  The component
    must have an `id` for persistence to work.

- persistence_type (a value equal to: 'local', 'session', 'memory'; optional):
    Where persisted user changes will be stored: memory: only kept in
    memory, reset on page refresh. local: window.localStorage, data is
    kept after the browser quit. session: window.sessionStorage, data
    is cleared once the browser quit.

- placeholder (string; optional):
    Placeholder.

- pointer (boolean; optional):
    Determines whether the input should have `cursor: pointer` style,
    `False` by default.

- popoverProps (dict; optional):
    Props passed down to `Popover` component.

    `popoverProps` is a dict with keys:

- presets (list of strings; optional):
    Time presets to display in the dropdown.

- radius (number; optional):
    Key of `theme.radius` or any valid CSS value to set
    `border-radius`, numbers are converted to rem,
    `theme.defaultRadius` by default.

- readOnly (boolean; optional):
    If set, the value cannot be updated.

- required (boolean; optional):
    Adds required attribute to the input and a red asterisk on the
    right side of label, `False` by default.

- reverseTimeControlsList (boolean; optional):
    If set, the time controls list are reversed, default `False`.

- rightSection (a list of or a singular dash component, string or number; optional):
    Content section rendered on the right side of the input.

- rightSectionPointerEvents (a value equal to: '-moz-initial', 'inherit', 'initial', 'revert', 'revert-layer', 'unset', 'auto', 'none', 'all', 'fill', 'painted', 'stroke', 'visible', 'visibleFill', 'visiblePainted', 'visibleStroke'; optional):
    Sets `pointer-events` styles on the `rightSection` element,
    `'none'` by default.

- rightSectionProps (dict; optional):
    Props passed down to the `rightSection` element.

- rightSectionWidth (string | number; optional):
    Right section width, used to set `width` of the section and input
    `padding-right`, by default equals to the input height.

- scrollAreaProps (boolean | number | string | dict | list; optional):
    Props passed down to all underlying `ScrollArea` components.

- secondsInputLabel (string; optional):
    `aria-label` of seconds input.

- secondsInputProps (boolean | number | string | dict | list; optional):
    Props passed down to seconds input.

- secondsStep (number; optional):
    Number by which seconds are incremented/decremented, `1` by
    default.

- size (optional):
    Controls input `height` and horizontal `padding`, `'sm'` by
    default.

- styles (boolean | number | string | dict | list; optional):
    Adds inline styles directly to inner elements of a component.  See
    Styles API docs.

- tabIndex (number; optional):
    tab-index.

- timeRangePresets (dict; optional):
    Generates a range of time values for the `presets` prop. Accepts a
    dictionary with `startTime`, `endTime`, and `interval` keys, where
    all values are strings in `hh:mm:ss` format. This overrides any
    values provided directly in the `presets` prop.

    `timeRangePresets` is a dict with keys:

- value (string; default ''):
    Value for controlled component.

- variant (string; optional):
    variant.

- visibleFrom (string; optional):
    Breakpoint below which the component is hidden with `display:
    none`.

- withAsterisk (boolean; optional):
    Determines whether the required asterisk should be displayed.
    Overrides `required` prop. Does not add required attribute to the
    input. `False` by default.

- withDropdown (boolean; optional):
    Determines whether the dropdown with time controls list should be
    visible when the input has focus, `False` by default.

- withErrorStyles (boolean; optional):
    Determines whether the input should have red border and red text
    color when the `error` prop is set, `True` by default.

- withSeconds (boolean; optional):
    Determines whether the seconds input should be displayed, `False`
    by default.

- wrapperProps (dict with strings as keys and values of type boolean | number | string | dict | list; optional):
    Props passed down to the root element.