pickerId/picker_id is a required prop to instantiate the Date Picker. The presence of pickerId/picker_id in your Date Picker also associates the label with the input, providing the ability to focus the Date Picker by clicking the label.
The defaultDate/default_date prop has a null or empty string value by default. You can pass an ISO date string (preferred rails method) or date object (preferred JS method) if you want a default value on page load. Use Ruby UTC DateTime objects and convert them to ISO date strings with DateTime.now.utc.iso8601.
If you use a Date object without UTC time standardization the Date Picker kit may misinterpret that date as yesterdays date (consequence of timezone differentials and the Javascript Date Object constructor). See this GitHub issue for more information and the anti-pattern examples below.
You can leverage the defaultDate/default_date prop with custom logic in your filter or controller files where the determination of the default value changes based on user interaction. The page can load with an initial default date picker value or placeholder text, then after filter submission save the submitted values as the "new default" (via state or params).
Setting the allowInput prop to true permits users to key values directly into the input. This prop is set to false by default.
The date picker is built with the text input kit. Text input props you pass to the date picker kit will be forwarded to the input, with a few exceptions. The value attribute is automatically handled and bound to whatever date string is contained by the input field. You cannot pass a custom value prop. id props passed to the date picker kit will be assigned to it's parent/wrapper div. The pickerId prop is passed directly to the input and is required to instatiate the date picker.
You must use inputAria or input_aria and inputData or input_data props if you wish to pass data or aria attributes to the text input kit. If you use data or aria props they will be passed to the date picker kit itself instead. Also be aware the default behavior of text input aria and data props is to pass those props to attributes on the wrapping div not on the input itself.
The placeholder prop has a default string value: "Select Date". You can replace this with your own string or an empty string if you'd prefer it blank.
Default label prop is "Date Picker". To remove the label set the hideLabel prop in React or the hide_label prop in Rails to true.
Your change handler function has access to two arguments: dateStr and selectedDates.
The first, dateStr, is a string of the chosen date. The second, selectedDates, is an array of selected date objects. In many use cases selectedDates will have only one value but you'll still need to access it from index 0.
NOTE: On Change does not account for manual input by users, so if your date picker sets allowInput, you should use the onClose method instead.
The onClose handler function has access to two arguments: dateStr and selectedDates.
The first, dateStr, is a string of the chosen date. The second, selectedDates, is an array of selected date objects. In many use cases selectedDates will have only one value but you'll still need to access it from index 0.
NOTE: onClose is the ideal handler function to use when allowInput is enabled.
To use the quickpick:
mode must be set to rangeselection_type must be set to quickpickThis date range variant uses hidden inputs to handle start and end dates. While they are not required props, it is advisable to specify a unique start_date_id, start_date_name, end_date_id, and end_date_name for each quick pick instance you place in a form and/or on a page.
Like all other date pickers, the quick pick does require a picker_id.
Use this_ranges_end_today/thisRangesEndToday to set end date on all ranges that start with 'this' to today's date. For instance, by default 'This Year' will set end day to 12/31/(current year), but if the this_ranges_end_today/thisRangesEndToday prop is used, end date on that range will be today's date.
The customQuickPickDates/custom_quick_pick_dates prop allows for the user/dev to define their own quick pick dates.
The prop accepts an object with two key/value pairs: dates & override (separate doc example below).
The dates property accepts an array of objects. Each object in the array has label and value properties. The label is what will be displayed in the UI of the dropdown menu. The value property is just the date that is going to be passed to the datepicker. The value property can be an array of two strings that represent a range, allowing for the dev to be extremely specific. Additionally, the dates array allows for a clean, simple API under that automatically converts dates in a common vernacular.
The timePeriod property accepts "days", "weeks", "months", "quarters" or "years", representing past time periods.
The amount property accepts any number.
The customQuickPickDates/custom_quick_pick_dates prop allows for an override boolean. The override allows for the user to completely override the quick pick dates that ship with the component. Default of override is set to true. If you would like to simply append your dates to the default quick pick dates, set this prop to false explicitly.
To set a default value using Quick Pick, use the defaultDate or default_date prop. This prop should match one of the labels displayed in the UI of the dropdown menu.
You can link a Quickpick Dropdown to standard DatePickers using the following props:
For the Quickpick DatePicker:
controls_start_id: ID of the DatePicker that should receive the start date.
controls_end_id: ID of the DatePicker that should receive the end date.
When a quickpick option like “This Year” is selected, it automatically populates the linked start and end inputs.
For the Start/End DatePickers:
sync_start_with: ID of the quickpick this start date is synced to.
sync_end_with: ID of the quickpick this end date is synced to.
When a user manually edits the start or end date, it clears the selected quickpick to prevent conflicting values.
You can find a full list of flatpickr events and hooks in their documentation.
Use window.addEventListener("DOMContentLoaded", () => {}), not document.addEventListener("DOMContentLoaded", () => {}).
Defaults to [1900, 2100]. Combine with min-max prop for best results.
By default selectType prop is disabled. To activate it set selectionType prop in JSX/TSX to month. To activate it set selection_type prop in a rails file to month.
By default selectType prop is disabled. To activate it set selectionType prop in JSX/TSX to week. To activate it set selection_type prop in a rails file to week.
To select time as well, you should pass the enableTime boolean prop. You can also enable timezone display by passing showTimezone.
Datepicker supports position options from Flatpickr Options Documentation. There are multiple positioning options to choose from.
Note: In order for the above prop to work properly, you must also send staticPosition={false} to your Datepicker kit instance.
If you are using the Datepicker within a Dialog, you cannot use the staticPosition/static_position prop.
Upon adding static={false} to the date picker, you will notice that the date picker detaches from the input field while scrolling. This is a known Flatpickr nuance. By adding the scrollContainer prop, you can tell the date picker which DOM container it should watch for scroll events. In this example, you can see that scrollContainer=".pb--page--content--main" is being passed in order to keep the date picker correctly positioned on page scroll.
Useage: scrollContainer: .validQuerySelectorHere
The requiredIndicator/required_indicator prop displays a red asterisk (*) next to the label to visually indicate that the field is required. This is purely visual and does not enforce validation—you can pair it with HTML required, client-side validation, or server-side validation as needed.
The custom_event_type prop allows you to specify a custom event that will trigger the date picker's initialization, in addition to the default initialization on DOMContentLoaded. This is particularly useful in dynamic contexts like Turbo Frame updates where you need to reinitialize the date picker after new content loads. For Turbo integration, use custom_event_type: "turbo:before-render" to ensure the date picker properly reinitializes after Turbo navigation events.
In this example, we demonstrate the setup pattern by connecting a button to dispatch a "datePickerLoader" event - while the date picker's event listener is properly configured through the custom_event_type prop, this demo only logs the event dispatch to the console to illustrate the connection structure.
This kit's options prop requires an array of objects, each of which will be used as the selectable options within the dropdown. Each option object can support any number of key-value pairs, but each MUST contain label, value and id.
The kit also comes with a custom event called "pb:dropdown:selected" which updates dynamically with the selection as it changes. See code snippet to see this in action.
In addition, a data attribute called data-option-selected with the selection is also rendered on the parent dropdown div.
The autocomplete prop can be used to add autocomplete or typeahead functionality to the Dropdown's default Trigger. This prop is set to 'false' by default.
multi_select is a boolean prop that if set to true will allow for multiple options to be selected from the Dropdown.
multi_select is set to false by default.
multiSelect can also be used with the autocomplete functionality.
By default, the multi_select prop will render selected options as the default form_pill. form_pill_props however can be used to customize these Pills with props that exist for the form_pill. Currently, only the 'color' and 'size' props are supported as shown here.
For the subtle variant, it is recommended that you set the Separators prop to false to remove the separator lines between the options for a cleaner look.
The dropdown is built using all of the following required subcomponents:
dropdown/dropdown_trigger is the UI component that users interact with to toggle the dropdown.
dropdown/dropdown_container is the floating container that wraps the list of dropdown options.
dropdown/dropdown_option renders options that are passed to the container.
Each of these subcomponents can be altered using global props and/or their respective props. See doc examples below for more information on each.
autocomplete prop can also be used in conjunction with the subcomponent structure.
The top-level Dropdown component optionally accepts any string through a label prop to produce a label above your trigger element.
Add an id to wire the label to the trigger so that clicking the label will move focus directly to the input, and open the drop-down.
dropdown/dropdown_option subcomponent accepts any child components to customize the options' contents and display. By default, options are Body kit text that is set by the label value from the option object.
Optionally utilize custom_display on the dropdown/dropdown_trigger subcomponent to customize its content after an option is selected. Pass in any combination of kits to create a custom display. When a user clicks on an option, the kits passed into custom_display will display as the selected option.
Make use of a script to help set the custom_display with the correct value. By using the pb:dropdown:selected event listener, you can target the kits with a querySelector and update them dynamically with the values needed to match the selected option. Make sure to add an ID to the kits being passed in.
The placeholder prop can also be used to customize the placeholder text for the default dropdown/dropdown_trigger.
The dropdown follows the typical rails pattern of utilizing hidden inputs for form submission. The hidden input value is the selected options' id.
Optionally replace the default trigger's select element by passing child components directly to the dropdown/dropdown_trigger.
The optional searchbar boolean prop can also be used on the dropdown/dropdown_container to render a searchbar with typeahead functionality within the dropdown itself. This is especially useful when a custom trigger is being used.
searchbar is set to false by default.
By default, dropdown option paddingX is set to sm and paddingY is set to xs, but this padding can be overridden using our global padding props. In this example we are setting the option padding to sm all around.
Use the dropdown/dropdown_option subcomponent structure to include custom layouts inside dropdown menus. Icons can be placed alongside the Body label text.
The blank_selection prop adds a blank option at the top of the dropdown options list. This allows users to explicitly clear their selection by choosing the blank option.
The blank selection option appears as the first item in the dropdown and has an empty value (id: "", value: ""). When selected, it effectively clears the dropdown selection.
The placeholder prop allows you to customize the placeholder text that appears when no option is selected in the dropdown.
The placeholder prop works with all dropdown variants (default, subtle, and quickpick). When no option is selected, the placeholder text is displayed. When an option is selected, the placeholder is replaced by the selected option's label. The default placeholder text is "Select..." if no placeholder is provided.
The clearable prop controls whether the clear (X) button appears in the dropdown. When set to false, the clear button is hidden.
This is useful in two scenarios:
The constrain_height prop limits the dropdown container height to 18em and enables vertical scrolling when the content exceeds this height. This prevents long dropdown lists from rendering off-screen.
When constrain_height is true, the dropdown will:
This is particularly useful for dropdowns with many options, such as long lists or quickpick variants with many date range options.
The close_on_click prop allows you to control when the Dropdown closes in response to click interactions. The value any reflects the default behavior, where the dropdown will close after any click. Set it to outside to ensure interactive elements as dropdown options are able to be interacted with or modified. Set it to inside for a dropdown that only closes when the input or dropdown menu is clicked.
The quickpick variant provides predefined date based options when variant:"quickpick" is used.
Open the Dropdown above to see the default options.
The quickpick variant automatically generates hidden inputs for start_date and end_date which are populated when a date range is selected. These inputs are ready for form submission.
You can customize the input names and IDs using the following props:
start_date_name - The name attribute for the start date input (default: "start_date_name")start_date_id - The ID attribute for the start date input (default: "start_date_id")end_date_name - The name attribute for the end date input (default: "end_date_name")end_date_id - The ID attribute for the end date input (default: "end_date_id")Example with custom names:
pb_rails("dropdown", props: {
variant: "quickpick",
start_date_name: "filter[start_date]",
start_date_id: "filter_start_date",
end_date_name: "filter[end_date]",
end_date_id: "filter_end_date"
})
The Dropdown kit also comes with a custom event called "pb:dropdown:selected" which updates dynamically with the selection as it changes. See code snippet to see this in action.
In addition, a data attribute called data-option-selected with the selection is also rendered on the parent dropdown div.
The optional range_ends_today prop can be used with the quickpick variant to set end date on all ranges that start with 'this' to today's date. For instance, by default 'This Year' will set end day to 12/31/(current year), but if range_ends_today prop is used, end date on that range will be today's date.
To set a default value for the Dropdown, you can use the label of the range you want set as default, for example "This Year", "Today", etc.
The custom_quick_pick_dates prop allows for defining custom quick pick date options for the dropdown. The prop accepts an object with two properties: dates and override.
The dates property accepts an array of objects. Each object has label and value properties. The label is what will be displayed in the dropdown menu. The value property defines the date range that will be selected, and can be:
["06/01/2022", "06/07/2022"])time_period and amount properties for dynamic date calculations:
time_period property accepts "days", "weeks", "months", "quarters", or "years", representing past time periods calculated from today.amount property accepts any number.The override property is a boolean that controls whether custom dates replace or append to the default quick pick options. Default is true (replaces defaults). Set to false to append your custom dates to the default quick pick options.
The quickpick variant can be synced with two DatePickers for a 3-input pattern. When a quickpick option is selected from the dropdown, both DatePickers are automatically populated. When either DatePicker is manually changed, the dropdown is cleared.
controls_start_id - ID of the start DatePicker to sync withcontrols_end_id - ID of the end DatePicker to sync withsync_start_with - ID of the dropdown to clear when start date changessync_end_with - ID of the dropdown to clear when end date changesThis pattern allows users to quickly select common date ranges or manually pick specific dates.
This example demonstrates the 3-input pattern with a default value. The dropdown is initialized with "This Month" selected, and both DatePickers are automatically populated with the corresponding start and end dates.
The default value can be set using the default_value prop with any of the quickpick option labels.
The requiredIndicator/required_indicator prop displays a red asterisk (*) next to the label, visually indicating that the field is required. This is purely visual and does not enforce validation.
You can use requiredIndicator/required_indicator with any validation approach: HTML5 validation via the required prop, client-side validation, or backend validation. For this reason, it works independently and doesn't need to be paired with the required prop.
The custom_event_type prop lets the dropdown clear when specific events are dispatched. Set it to a comma-separated list of event names (e.g. Turbo or app-specific); when any of those events fire with optional detail: { dropdownId }, the matching dropdown clears. You can also listen for selection changes (pb:dropdown:selected), clear by dispatching pb:dropdown:clear, or set the selection by dispatching pb:dropdown:select with detail: { dropdownId, optionId } (or optionIds for multi-select).
The examples show five distinct variants (default, multi select, autocomplete, quick pick, custom display). In each example, the first button clears the dropdown by dispatching a custom event that the dropdown listens for via custom_event_type. The second button sets the selection by dispatching pb:dropdown:select. The third button simulates a form submit by dispatching another custom event in custom_event_type, so the dropdown clears as it would after a real form submission.
Turbo events (e.g. turbo:frame-load, turbo:frame-render, turbo:submit-end) often fire for many actions or across the page, so using them as custom_event_type can clear the dropdown more often than intended. Use them when that scope is what you want; otherwise use app-specific event names and dispatch with detail: { dropdownId } when the action happens, or dispatch pb:dropdown:clear from your own handler.
Dropdowns with subcomponent structures that show custom displays (e.g. custom trigger or custom display) require a pb:dropdown:selected listener to update the visible UI from event.detail when a selection is made; clear is handled by the kit.
The MultiLevelSelect kit renders a multi leveled select dropdown based on data from the user. treeData is a required prop that is expected to contain the data in the form of an array of objects. See code snippet for an example data array.
For the React version of the kit, the onSelect prop returns an array of objects. This array contains all checked items irrespective of whether it is a parent, child or grandchild. Open the console on this example and check and uncheck checkboxes to see this is action!
For the Rails version of the kit, there is no onselect. The form submits as a array of strings, following the typical rails pattern of utilizing hidden inputs. The strings are the values of the selected items' ids. For example, ["103", "106", "107"].
Optionally enable the single variant to replace checkboxes with radios so the input accepts and returns only a single selection.
Dynamically control your selectable options by passing hideRadio: true to any node within your tree data to omit that node's radio selector. In this example we've hidden all radios except ultimate children (nodes without descendants).
The returnAllSelected or return_all_selected prop can be used when users want data on all checked nodes from the dropdown, irrespective of whether it is a parent or child node.
NOTE: This variant also does not automatically uncheck the parent when any of the child nodes are unchecked. returnAllSelected is set to false by default.
NOTE: For larger trees that may return many pill selections, you can optionally set input_display: "none"(for Rails) or inputDisplay = "none"(for React) to hide all pills within the input.
Use the inputDisplay/input_display prop to optionally display only the count in the display as opposed to multiple pills. This prop is set to 'pills' by default.
NOTE: inputDisplay/input_display is particularly useful for larger trees that may return many pill selections, helping to keep the input field clean and compact. This prop should not be used with the Single Select variant.
selected_ids is an optional prop that accepts an array of ids that, if present, will mark the corresponding nodes on the treeData as checked on page load.
Items that include checked:true on the treeData itself will also be selected on page load, even without being passed to selectedIds.
When an item is marked as checked on page load by any means, the dropdown will expand to show the checked items for easier accessibility.
When using selected_ids and variant: "single" together (see single select doc examples), the selected_ids array should contain only one id, because only one item can be selected and displayed at a time. If the selected_ids array has multiple ids in it, the first id in the array will be the treeData node checked upon page load.
Change the form pill color by passing the optional pill_color prop. Product, Data, and Status colors are available options. Check them out here in the Form Pill colors example.
In order to clear the multilevelselect selection using an external trigger (like a reset button), the clearMultiLevelSelect function can be used. See the code snippet below to see this in action. The function is scoped by id so an id MUST be used on the multilevelselect kit and passed to the function as shown for it to work.
The MultiLevelSelect component optionally accepts a label prop to produce a label above the input.
Add an id to wire the label to the input so that clicking the label will move focus directly to the input, and open the drop-down.
To disable individual items in the treeData, include disabled:true within the object on the treeData that you want disabled. See the code snippet below for an example of how to do this.
If a parent is selected, the parent will be returned in the selected items list, even if it has disabled children.
Individual items can also be disabled by including the disabled:true within the object on the treeData for the returnAllSelected/return_all_selected variant. As noted above, this variant will return data on all checked nodes from the dropdown, irrespective of whether it is a parent or child node.
For the default variant, disabling the parent item will automatically disable it's children as well.
If you want to be able to disable a parent WITHOUT disabling it's children, use the returnAllSelected/return_all_selected variant.
For the returnAllSelected/return_all_selected variant, disabling the parent item will NOT automatically disable it's children since this version allows you to select a parent even if all children are unselected.
You can manually pass disabled:true to any and all children of a disabled parent if you want to do so.
Individual items can be disabled by including disabled: true within the object on the treeData for the single variant. Disabled options are visibly disabled in the dropdown UI and cannot be selected via mouse click or keyboard navigation. When a parent node is disabled, all of its children are automatically disabled as well.
The requiredIndicator/required_indicator prop displays a red asterisk (*) next to the label, visually indicating that the field is required. This is purely visual and does not enforce validation.
You can use requiredIndicator/required_indicator with any validation approach: HTML5 validation via the required prop, client-side validation, or backend validation. For this reason, it works independently and doesn't need to be paired with the required prop.
Use the placeholder prop to customize the initial text shown in the input when nothing is selected. The default is Start typing....
To create a select with non-selectable subheaders, use a Custom Select component to render a native <select> containing <optgroup> elements. The optgroup HTML element groups related options under a non-selectable label in the dropdown.
Select w/ Error shows that an option must be selected or is invalid (i.e. when used in a form it signals a user to fix an error).
Inspect the element and notice the data-attribute being added to the <select> element
The multiple prop enables multiple selections; however, for a better user experience, we recommend our Typeahead kit.
Use the input_options / inputOptions prop to pass additional attributes directly to the underlying <select> element instead of the outer wrapper. This is useful for applying data attributes, custom IDs, or other HTML attributes that need to be on the select element itself.
The requiredIndicator/required_indicator prop displays a red asterisk (*) next to the label, visually indicating that the field is required. This is purely visual and does not enforce validation.
You can use requiredIndicator/required_indicator with any validation approach: HTML5 validation via the required prop, client-side validation, or backend validation. For this reason, it works independently and doesn't need to be paired with the required prop.
Default Selectable Cards are multi select by default.
Single Select allows only one selectable card in the set to be selected.
Selectable Cards can pass text or block content.
Selectable Cards can pass images with optional text.
Selectable Cards can show an input indicating state.
When using custom icons it is important to introduce a "clean" SVG. In order to ensure these custom icons perform as intended within your kit(s), ensure these things have been modified from the original SVG markup:
Attributes must be React compatible e.g. xmlns:xlink should be xmlnsXlink and so on. There should be no hyphenated attributes and no semi-colons!.
Fill colors with regards to g or path nodes, e.g. fill="black", should be replaced with currentColor ala fill="currentColor". Your mileage may vary depending on the complexity of your SVG.
Pay attention to your custom icon's dimensions and viewBox attribute. It is best to use a viewBox="0 0 512 512" starting point when designing instead of trying to retrofit the viewbox afterwards!
You must source your own SVG into component/view you are working on. This can easily be done in programmatic and maintainable ways.
So long as you have a valid React <SVG> node, you can send it as the customIcon prop and the kit will take care of the rest.
Some Rails applications use only webpack(er) which means using image_url will be successful over image_path in most cases especially development where Webpack Dev Server is serving assets over HTTP. Rails applications still using Asset Pipeline may use image_path or image_url. Of course, YMMV depending on any custom configurations in your Rails application.
Error shows that the radio option must be selected or is invalid (i.e. when used in a form it signals a user to fix an error).
Use the custom_children prop to enable the use of kits instead of text labels.
When using a custom checkbox wrapped in the Checkbox kit, hidden inputs are not automatically included and cannot be prop enabled. Manually add a hidden input before the checkbox if necessary to submit a value when the checkbox is unchecked (as is standard in Rails forms).
If you want to use indeterminate, "check/uncheck all" checkboxes, add indeterminate_main: true and an id to the main checkbox. Then, add an indeterminate_parent prop with the main checkbox's id to the children checkboxes.
If you want to customize the main checkbox labels, set an array indeterminate_main_labels with "Check All" and "Uncheck All" labels.
The way to access hidden inputs for form submission depends on which version of the kit being used within the form context.
If using the Rails Checkbox version of the kit, set hidden_input: true. Inspect Checkbox #1 in the example above to see the hidden input in the DOM.
If using the Form Builder version of the kit (reference the Form kit page for more on these), the hidden input will appear if the input has a set unchecked_value. Inspect Checkbox #2 in the example above (and the two checkbox examples on the Form kit page) to see the hidden input in the DOM. See the Rails check_box FormHelper docs for more.
Use the Time Picker for time-only selection. For date and time selection, use the DatePicker with Time Selection Enabled instead.
Set time_format / timeFormat to 24hour to display the time selection dropdown in a 24-hour format.
The default_time / defaultTime prop sets a default time value and accepts both 12-hour and 24-hour formats.
Enable timezone display by passing show_timezone / showTimezone.
Use the min_time / minTime and max_time / maxTime props to restrict the selectable time range. This example demonstrates minimum-only, maximum-only, and combined ranges in both 12-hour and 24-hour formats.
The requiredIndicator/required_indicator prop displays a red asterisk (*) next to the label, visually indicating that the field is required. This is purely visual and does not enforce validation.
You can use requiredIndicator/required_indicator with any validation approach: HTML5 validation via the required prop, client-side validation, or backend validation. For this reason, it works independently and doesn't need to be paired with the required prop.
