Custom Styling

Customize the timepicker appearance to match your brand

Classes you can target in your own CSS.

.tp-ui-select-timeHeader label.
.tp-ui-hourHour field.
.tp-ui-clock-faceClock face with the hour and minute tips.
.tp-ui-footerFooter with the buttons.
.tp-ui-wrapperThe picker's root element.
.tp-ui-type-modeAM/PM switch in 12-hour mode.
.tp-ui-minutesMinute field.
.tp-ui-clock-handClock hand.

CSS Variables

Timepicker-UI uses CSS custom properties (variables) for easy customization. Override these variables to change colors and styles:

Color and Shape Tokens

Defaults of the basic theme. Each built-in theme sets its own values.

index.css

1:root {
2  /* Surfaces */
3  --tp-bg: #ece6ee;
4  --tp-surface: #e6e0e9;
5  --tp-surface-hover: #c8b3fd;
6  --tp-input-bg: #e6e0e9;
7
8  /* Text */
9  --tp-text: #1d1b20;
10  --tp-text-secondary: #49454f;
11  --tp-text-disabled: rgba(156, 155, 155, 0.6);
12  --tp-text-type-time: #49454f;
13  --tp-text-icon: #4e545a;
14
15  /* Primary and containers (Material Design 3 roles) */
16  --tp-primary: #6750a4;
17  --tp-on-primary: #ffffff;
18  --tp-primary-container: #eaddff;
19  --tp-on-primary-container: #21005d;
20
21  /* AM/PM */
22  --tp-am-pm-active: #ffd8e4;
23  --tp-am-pm-text-selected: #633b48;
24  --tp-am-pm-text-unselected: #49454f;
25
26  /* Borders and shape */
27  --tp-border: #000;
28  --tp-outline: #6750a4;
29  --tp-shadow: unset;
30  --tp-border-radius: 28px;
31
32  /* Font (see "Font" below) */
33  /* --tp-font-family: not set, falls back to 'Roboto', sans-serif */
34
35  /* Focus ring (see "Focus Ring" below) */
36  /* --tp-focus-ring: not set, falls back to --tp-primary */
37  /* --tp-shadow-focus-ring: not set, defaults to none */
38
39  /* Timezone dropdown */
40  --tp-dropdown-option-bg: #ffffff;
41  --tp-dropdown-option-text: #000000;
42  /* --tp-dropdown-option-hover-text: not set, falls back to
43     --tp-dropdown-option-text. Text color of a hovered or
44     keyboard-focused option. */
45}

Themes other than basic set their values on .tp-ui-modal[data-theme], which wins over :root. To override a token for every theme, set it on .tp-ui-wrapper. For one picker, use the class you pass in ui.cssClass (.tp-ui-wrapper.my-theme).

Tokens that do nothing

No rule reads --tp-tertiary-container, --tp-on-tertiary-container, --tp-hover-bg or --tp-radius. Setting them changes nothing, and 5.0 removes them.

Font

To change the font, set --tp-font-family. .tp-ui-wrapper reads it with font-family: var(--tp-font-family, 'Roboto', sans-serif), and the time fields and buttons in the modal inherit it. Set the variable on :root or .tp-ui-modal for every picker, or on the class you pass in ui.cssClass for one picker. The picker adds that class to .tp-ui-wrapper.

index.css

1/* ui: { cssClass: 'my-theme' } */
2.tp-ui-wrapper.my-theme {
3  --tp-font-family: 'Inter', system-ui, sans-serif;
4}

Setting font-family directly on .tp-ui-wrapper.my-theme also works.

Seconds Sizes

Used when clock.showSeconds is on, so three fields fit in the header, the wheel and the range tabs.

index.css

1:root {
2  /* Header fields, 12h */
3  --tp-size-input-seconds-12h: 64px;
4  --tp-size-input-seconds-12h-narrow: 58px; /* screens 330px wide or less */
5  --tp-size-colon-seconds-12h: 12px;
6  --tp-font-size-seconds-12h: 36px;
7
8  /* Header fields, 24h */
9  --tp-size-input-seconds-24h: 80px;
10  --tp-size-input-seconds-24h-narrow: 74px; /* 330px or less, and landscape up to 480px tall */
11  --tp-size-colon-seconds-24h: 20px;
12  --tp-font-size-seconds-24h: 44px;
13
14  /* Wheel and range tabs */
15  --tp-wheel-column-width-seconds: 64px;
16  --tp-wheel-separator-width-seconds: 16px;
17  --tp-range-tab-value-font-size-seconds: 14px;
18}

Keyboard View in Landscape

Size of the keyboard input view on landscape screens up to 480px tall.

index.css

1:root {
2  --tp-mobile-landscape-width: 328px;
3  --tp-mobile-landscape-height: 258px;
4  --tp-mobile-landscape-height-range: 287px;    /* range plugin */
5  --tp-mobile-landscape-height-timezone: 326px; /* timezone selector */
6}

Compact-Wheel Popover

Used when compact-wheel opens as a popover next to the input (wheel.placement is set). The popover is at least as wide as the input and --tp-popover-min-width, at most --tp-popover-max-width, and never closer to the viewport edge than --tp-popover-edge-margin.

index.css

1:root {
2  --tp-popover-gap: 4px;          /* space between the input and the popover */
3  --tp-popover-edge-margin: 4px;  /* smallest space to the viewport edge */
4  --tp-popover-min-width: 260px;
5  --tp-popover-max-width: 328px;
6  --tp-popover-shadow: 0 4px 24px rgba(0, 0, 0, 0.15);
7  /* --tp-popover-radius: not set, falls back to --tp-border-radius */
8}

The gap, edge margin and widths are read from .tp-ui-modal, so set them on :root or .tp-ui-modal, not on .tp-ui-wrapper. Any CSS length works, for example px, rem or calc().

Scrollbar Gap

--tp-scrollbar-gap is set by the picker, not by you. While a picker locks page scroll (ui.allowPageScroll: false, the default), it is set on <html> to the width of the removed scrollbar, or 0px when there was none. Read it in your own CSS to keep fixed elements in place. See Scroll lock and fixed headers.

Embedded card surface

#

An embedded inline picker (ui.inline.embedded) takes its card background, corner radius and backdrop filter from three variables. They fall back to --tp-bg, --tp-radius-md and --tp-backdrop-filter. New in 4.7.0.

index.css

1.my-dialog .tp-ui--embedded {
2  --tp-embedded-bg: transparent;
3  --tp-embedded-radius: 0;
4  --tp-embedded-backdrop-filter: none;
5}

Compact keyboard view

#

Shrink the time fields of the keyboard view with three variables. --tp-size-input is the field width, --tp-size-input-mobile the height on narrow screens and --tp-time-input-font-size the size of the numbers. New in 4.7.0.

index.css

1.tp-ui-wrapper {
2  --tp-size-input: 72px;
3  --tp-size-input-mobile: 56px;
4  --tp-time-input-font-size: 36px;
5}

Focus Ring

#

Keyboard focus shows one 3px ring in --tp-focus-ring, 2px outside the control. When --tp-focus-ring is not set, the ring uses --tp-primary. The width and offset come from --tp-outline-width-thick and --tp-outline-offset.

AM/PM and the time fields draw the ring inside their edge. On the selected field it uses --tp-on-primary-container, on the selected AM/PM button --tp-am-pm-text-selected.
Range tabs and wheel columns use the same 3px ring. Only the keyboard-focused timezone option gets a thinner 2px ring inside its edge, set by --tp-outline-width.
With prefers-contrast: more the ring is 4px. In forced-colors mode it uses the system Highlight color.
--tp-shadow-focus-ring adds a box-shadow to the ring. It defaults to none.
There is no --tp-focus-ring-halo token any more. Setting it has no effect.

index.css

1.tp-ui-wrapper.my-theme {
2  --tp-focus-ring: #0b57d0;
3
4  /* Optional, off by default */
5  --tp-shadow-focus-ring: 0 0 0 6px rgba(11, 87, 208, 0.25);
6}

Creating Custom Themes

#

Timepicker-UI comes with several built-in themes:

Available Themes

index.ts

1import { TimepickerUI } from 'timepicker-ui';
2
3// Material Design 2 theme (purple/magenta)
4const picker1 = new TimepickerUI(input1, { ui: { theme: 'm2' } });
5
6// Material Design 3 theme (green)
7const picker2 = new TimepickerUI(input2, { ui: { theme: 'm3-green' } });
8
9// Dark theme
10const picker3 = new TimepickerUI(input3, { ui: { theme: 'dark' } });
11
12// Crane theme with rounded corners
13const picker4 = new TimepickerUI(input4, { ui: { theme: 'crane' } });
14
15// Crane-straight theme (sharp edges)
16const picker5 = new TimepickerUI(input5, { ui: { theme: 'crane-straight' } });

To make your own theme, give the picker a class with ui.cssClass and set the CSS variables under .tp-ui-wrapper.your-class. The picker adds the class to its .tp-ui-wrapper when it opens. ui.theme accepts only the 12 built-in names.

Custom Theme Example

index.css

1.tp-ui-wrapper.my-theme {
2  --tp-bg: #ffffff;
3  --tp-text: #000000;
4  --tp-primary: #6200ee;
5  --tp-on-primary: #ffffff;
6  --tp-surface: #e0e0e0;
7  --tp-surface-hover: #ece0fd;
8  --tp-input-bg: #e4e4e4;
9  --tp-border: #d6d6d6;
10  --tp-text-secondary: #a9a9a9;
11  --tp-text-type-time: #787878;
12  --tp-text-icon: #4e545a;
13  --tp-text-disabled: rgba(156, 155, 155, 0.6);
14  --tp-shadow: 0 10px 35px 0 rgba(0, 0, 0, 0.25);
15  --tp-border-radius: 4px;
16}

Using Your Custom Theme

index.ts

1import { TimepickerUI } from 'timepicker-ui';
2
3const picker = new TimepickerUI('#timepicker', {
4  ui: { cssClass: 'my-theme' }
5});
6
7picker.create();

You can also start from a built-in theme: ui: { theme: 'dark', cssClass: 'my-theme' }. Your values win because the wrapper sits inside the themed modal.

Switching Themes at Runtime

There is no setTheme() method. Change ui.theme or ui.cssClass with setOptions(). The picker builds its modal when it opens, so the new theme shows the next time it opens. A picker that is open re-renders right away. Load the CSS file of every theme you switch to.

index.ts

1import 'timepicker-ui/main.css';
2import 'timepicker-ui/theme-dark.css';
3
4const picker = new TimepickerUI('#timepicker', {
5  ui: { theme: 'basic' }
6});
7
8picker.create();
9
10picker.setOptions({ ui: { theme: 'dark' } });

Material Design 3 Ripple Effect

#

Pressing a control shows a ripple that grows from the press point. Hover, keyboard focus and press also show a state layer, a faint overlay in the control's text color. Keyboard activation does not start a ripple. With prefers-reduced-motion, a press shows only the pressed layer, without the ripple.

Where It Applies

OK, Cancel and Clear buttons
AM/PM buttons
Hour, minute and second fields
The view-switch icon
Range tabs (range plugin) and the timezone trigger (timezone plugin)

Customizing the Ripple

Controls with the effect carry the data-md3-ripple attribute. Their ::before is the state layer and ::after is the ripple. Both use the control's text color (currentColor). On the selected time field that is --tp-on-primary-container. Strength and timing come from these tokens (defaults shown):

index.css

1.tp-ui-wrapper.my-theme {
2  --tp-state-hover-opacity: 0.08;
3  --tp-state-focus-opacity: 0.1;
4  --tp-state-pressed-opacity: 0.1;
5  --tp-ripple-opacity: 1; /* multiplies the pressed opacity for the ripple */
6  --tp-duration-ripple: 700ms;
7  --tp-duration-ripple-fade: 500ms;
8}
9
10/* Turn the ripple off and keep the state layers */
11.tp-ui-wrapper.no-ripple {
12  --tp-ripple-opacity: 0;
13}

Complete Custom Theme Example

#

Here's a complete example of a custom purple theme:

theme-purple.css

1.tp-ui-wrapper.purple {
2  --tp-bg: #faf5ff;
3  --tp-text: #1e1b4b;
4  --tp-primary: #8b5cf6;
5  --tp-on-primary: #ffffff;
6  --tp-surface: #ede9fe;
7  --tp-surface-hover: #ddd6fe;
8  --tp-input-bg: #f3e8ff;
9  --tp-border: #c4b5fd;
10  --tp-text-secondary: #7c3aed;
11  --tp-text-type-time: #6d28d9;
12  --tp-text-icon: #7c3aed;
13  --tp-text-disabled: #a78bfa;
14  --tp-shadow: 0 10px 35px 0 rgba(139, 92, 246, 0.3);
15  --tp-border-radius: 16px;
16  --tp-font-family: 'Inter', system-ui, sans-serif;
17}

index.ts

1import { TimepickerUI } from 'timepicker-ui';
2import 'timepicker-ui/main.css';
3import './theme-purple.css';
4
5const picker = new TimepickerUI('#timepicker', {
6  ui: { cssClass: 'purple' }
7});
8
9picker.create();

Browser Compatibility: CSS custom properties are supported in all modern browsers. For older browsers, provide fallback values or use a PostCSS plugin to generate static CSS. Test your custom themes across different browsers to ensure consistent appearance.; View built-in themes