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.
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 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.
| Props | Type | Values |
|---|---|---|
gap |
array
|
none
xxs
xs
sm
md
lg
xl
|
max_width |
array
|
0%
xs
sm
md
lg
xl
xxl
0
none
100%
|
min_width |
array
|
0%
xs
sm
md
lg
xl
xxl
0
none
100%
|
width |
array
|
0%
xs
sm
md
lg
xl
xxl
0
none
100%
|
z_index |
array
|
1
2
3
4
5
6
7
8
9
10
max
|
number_spacing |
array
|
tabular
|
shadow |
array
|
none
deep
deeper
deepest
|
line_height |
array
|
tightest
tighter
tight
normal
loose
looser
loosest
|
display |
array
|
block
inline_block
inline
flex
inline_flex
none
grid
|
cursor |
array
|
auto
default
none
contextMenu
help
pointer
progress
wait
cell
crosshair
text
verticalText
alias
copy
move
noDrop
notAllowed
grab
grabbing
eResize
nResize
neResize
nwResize
sResize
seResize
swResize
wResize
ewResize
nsResize
neswResize
nwseResize
colResize
rowResize
allScroll
zoomIn
zoomOut
|
flex_direction |
array
|
row
column
rowReverse
columnReverse
|
flex_wrap |
array
|
wrap
nowrap
wrapReverse
|
justify_content |
array
|
start
end
center
spaceBetween
spaceAround
spaceEvenly
|
justify_self |
array
|
auto
start
end
center
stretch
|
align_items |
array
|
flexStart
flexEnd
start
end
center
baseline
stretch
|
align_content |
array
|
start
end
center
spaceBetween
spaceAround
spaceEvenly
|
align_self |
array
|
auto
start
end
center
stretch
baseline
|
flex |
array
|
auto
initial
0
1
2
3
4
5
6
7
8
9
10
11
12
none
|
flex_grow |
array
|
1
0
|
flex_shrink |
array
|
1
0
|
order |
array
|
1
2
3
4
5
6
7
8
9
10
11
12
|
position |
array
|
relative
absolute
fixed
sticky
|
hover |
array
|
|
border_radius |
array
|
none
xs
sm
md
lg
xl
rounded
|
text_align |
array
|
start
end
left
right
center
justify
justify-all
match-parent
|
overflow |
array
|
visible
hidden
scroll
auto
|
truncate |
array
|
1
2
3
4
5
|
left |
array
|
0
xxs
xs
sm
md
lg
xl
auto
initial
inherit
|
top |
array
|
0
xxs
xs
sm
md
lg
xl
auto
initial
inherit
|
right |
array
|
0
xxs
xs
sm
md
lg
xl
auto
initial
inherit
|
bottom |
array
|
0
xxs
xs
sm
md
lg
xl
auto
initial
inherit
|
vertical_align |
array
|
baseline
super
top
middle
bottom
sub
text-top
text-bottom
|
height |
array
|
auto
xs
sm
md
lg
xl
xxl
xxxl
|
min_height |
array
|
auto
xs
sm
md
lg
xl
xxl
xxxl
|
max_height |
array
|
auto
xs
sm
md
lg
xl
xxl
xxxl
|
overflow_x |
array
|
visible
hidden
scroll
auto
|
overflow_y |
array
|
visible
hidden
scroll
auto
|
classname |
string
|
|
dark |
boolean
|
|
column_gap |
string
|
|
row_gap |
string
|
|
margin |
array
|
none
xxs
xs
sm
md
lg
xl
|
margin_bottom |
array
|
none
xxs
xs
sm
md
lg
xl
|
margin_left |
array
|
none
xxs
xs
sm
md
lg
xl
|
margin_right |
array
|
none
xxs
xs
sm
md
lg
xl
|
margin_top |
array
|
none
xxs
xs
sm
md
lg
xl
|
margin_x |
array
|
none
xxs
xs
sm
md
lg
xl
|
margin_y |
array
|
none
xxs
xs
sm
md
lg
xl
|
padding |
array
|
none
xxs
xs
sm
md
lg
xl
|
padding_bottom |
array
|
none
xxs
xs
sm
md
lg
xl
|
padding_left |
array
|
none
xxs
xs
sm
md
lg
xl
|
padding_right |
array
|
none
xxs
xs
sm
md
lg
xl
|
padding_top |
array
|
none
xxs
xs
sm
md
lg
xl
|
padding_x |
array
|
none
xxs
xs
sm
md
lg
xl
|
padding_y |
array
|
none
xxs
xs
sm
md
lg
xl
|
group_hover |
boolean
|
|
id |
string
|
|
data |
hashprop
|
|
aria |
hashprop
|
|
html_options |
hashprop
|
|
children |
proc
|
|
style |
hashprop
|
| Props | Type | Values | Default |
|---|---|---|---|
options |
array
|
||
label |
string
|
||
name |
string
|
||
error |
string
|
||
required |
boolean
|
false
|
|
default_value |
string
|
||
blank_selection |
string
|
||
custom_quick_pick_dates |
hashprop
|
||
variant |
enum
|
default
subtle
quickpick
|
default
|
separators |
boolean
|
true
|
|
autocomplete |
boolean
|
false
|
|
searchbar |
boolean
|
false
|
|
multi_select |
boolean
|
false
|
|
form_pill_props |
hashprop
|
||
range_ends_today |
boolean
|
false
|
|
controls_end_id |
string
|
||
controls_start_id |
string
|
||
clearable |
boolean
|
true
|
|
start_date_id |
string
|
start_date_id
|
|
start_date_name |
string
|
start_date_name
|
|
end_date_id |
string
|
end_date_id
|
|
end_date_name |
string
|
end_date_name
|
|
placeholder |
string
|
||
constrain_height |
boolean
|
false
|
