Harmonia

Appearance

Week Picker ​

Allows users to select a whole ISO week, either by typing it directly or by choosing from a month calendar whose rows are weeks (Monday-first).

Usage ​

Use the Week Picker when a field represents a whole week (a timesheet week, a planning week, a weekly report) rather than a single day. For a specific day use the Date Picker instead.

Keyboard Handling ​

The user can use the following keyboard shortcuts in order to navigate through the week picker:

  • Enter / Space - Opens the popup, or selects the focused week when open.
  • Up / Down - Moves focus to the previous/next week, moving the visible month when needed.
  • Home / End - Moves focus to the first/last visible week.
  • PageUp / PageDown - Moves focus to the same week of the previous/next month.
  • Esc - Closes the popup.

API Reference ​

Component attribute(s) ​

x-h-week-picker
x-h-week-picker-trigger
x-h-week-picker-popup

Attributes ​

x-h-week-picker ​

AttributeValuesRequiredDescription
data-sizesm
default		falseChanges the size of the week picker.

x-h-week-picker-popup ​

AttributeValuesRequiredDescription
data-alignbottom-start
bottom
bottom-end
right-start
right
right-end
left-start
left
left-end
top-start
top
top-end		falseAligns the popup relative to the picker trigger.
data-aria-prev-monthstringfalseSets the aria-label attribute value for the previous month button.
data-aria-next-monthstringfalseSets the aria-label attribute value for the next month button.
data-week-labelstringfalseSets the text placed before the week number in the input display value and in the week row labels. Defaults to Week.
data-week-column-labelstringfalseSets the accessible label of the week number column header (shown as #). Defaults to Week number.

Modifiers ​

ModifierDescription
tableUse when the input is inside a table

Configuration ​

You can pass a configuration object to the popup as an expression or as a value.

KeyDescription
localeThe locale of the calendar as a BCP 47 language tag. If not provided, it is taken from the page's <html lang> attribute, then the browser locale.

Model ​

The week picker reads and writes weeks as ISO 8601 YYYY-Www strings (e.g. "2025-W23"). The week-numbering year follows ISO 8601 (the week containing the year's first Thursday is week 1), so early-January and late-December weeks may carry the neighbouring year. The text input displays the selection as Week <n>, <year> by default. The Week text can be customised via data-week-label on the popup.

Events ​

EventDescription
changeFired on the inner input when the user picks a week from the popup or types a valid week. The event bubbles, so a listener can be placed on the x-h-week-picker element. Read the new value from the bound model, as the input's own value holds the formatted display text instead.

There is no need to use $watch to react to user selection - listen for change instead. See Listening for changes.

Validation timing ​

By default this control shows native-constraint errors (for example required) only after the user interacts with it or attempts to submit, not on page load. To validate on load instead, set data-validate="immediate" on a wrapping x-h-fieldset, x-h-field, or any ancestor element. Setting aria-invalid="true" yourself always shows the error immediately. See Fieldset for details.

Examples ​

html
<div x-h-week-picker x-data="{ week: '' }">
  <input type="text" id="week-input-1" />
  <button x-h-week-picker-trigger aria-label="Choose week"></button>
  <div x-h-week-picker-popup x-model="week"></div>
</div>

Listening for changes ​

html
<div x-h-week-picker x-data="{ week: '' }" @change="console.log('Selected week:', week)">
  <input type="text" id="week-input-change" />
  <button x-h-week-picker-trigger aria-label="Choose week"></button>
  <div x-h-week-picker-popup x-model="week"></div>
</div>

With locale ​

html
<div x-h-week-picker x-data="{ week: '2026-W07' }">
  <input type="text" id="week-input-locale" />
  <button x-h-week-picker-trigger aria-label="Choose week"></button>
  <div x-h-week-picker-popup="{ locale: 'bg-BG' }" x-model="week"></div>
</div>

Preselected value ​

html
<div x-h-week-picker x-data="{ week: '2026-W07' }">
  <input type="text" id="week-input-preselected" />
  <button x-h-week-picker-trigger aria-label="Choose week"></button>
  <div x-h-week-picker-popup x-model="week"></div>
</div>

Invalid ​

Reacts to the native invalid state or to the aria-invalid attribute.

html
<div x-h-week-picker x-data="{ week: '2026-W07' }">
  <input type="text" id="week-input-invalid" aria-invalid="true" />
  <button x-h-week-picker-trigger aria-label="Choose week"></button>
  <div x-h-week-picker-popup x-model="week"></div>
</div>

Disabled ​

Set the native disabled attribute on the inner input to disable the whole picker.

html
<div x-h-week-picker x-data="{ week: '2026-W07' }">
  <input type="text" id="week-input-disabled" disabled />
  <button x-h-week-picker-trigger aria-label="Choose week"></button>
  <div x-h-week-picker-popup x-model="week"></div>
</div>

Read-only ​

Set the native readonly attribute on the inner input. The value is shown with a muted background, and neither typing nor the popup can change it.

html
<div x-h-week-picker x-data="{ week: '2026-W07' }">
  <input type="text" id="week-input-readonly" readonly />
  <button x-h-week-picker-trigger aria-label="Choose week"></button>
  <div x-h-week-picker-popup x-model="week"></div>
</div>