Dropdown

Select dropdown for choosing one option from a predefined list. Supports static options, dynamic options from queries, and query‑centric data binding.

Use Cases

• Single‑choice selection from predefined list (status, category, type)
• Country, state, or region selection
• Priority, difficulty, or rating selection
• Data‑bound dropdowns connected to page data sources

Properties

name

Unique field name. Type: string. Required.

label

Label displayed above dropdown. Type: string. Required.

options

Static array of selectable options (fallback if optionsQuery not defined). Use for simple fixed lists like Yes/No, Priority, Status. Type: array. Minimum items: 1.

optionsQuery

Load dropdown options dynamically from a list query (e.g., States, Categories, Products). Takes precedence over static options array. Type: object.

Tip: Use optionsQuery for lookup tables (States, Categories, Products) where options come from database. Don’t use for simple fixed lists (Yes/No, High/Medium/Low) – use static options array instead.

placeholder

Placeholder shown when no option selected. Type: string.

required

Whether selection is required. Type: boolean. Default: false.

defaultValue

Default selected value (must match one of the option values). Type: string.

id

Unique component identifier for targeting with JavaScript and event handlers. Type: string.

Tip: Required when using event handlers or JavaScript to target this component. Can be omitted for simple forms without JavaScript.

width

CSS width of the dropdown container. Type: string. Default: 100%.

Tip: Use ‘100%’ for standalone dropdowns. Use ‘75%’ or ‘25%’ when paired with other fields in Grid/Flex. Use fixed pixel widths (e.g., ‘200px’) for short option lists.

multiple

Allow selection of multiple options (renders as multi‑select listbox). Type: boolean. Default: false.

Visual Impact: false – Single selection dropdown (default) – one option at a time. true – Multi‑select listbox – hold Ctrl/Cmd to select multiple options.

Tip: Use false (default) for most use cases – cleaner UX. Use true only when users genuinely need multiple selections (tags, categories). For 2‑5 multi‑select options, consider using Checkbox components instead.

events

JavaScript event handlers for dropdown interactions (onChange, onFocus, onBlur). Type: object.

Sub‑properties:

• onChange – JavaScript executed when selection changes. Type: string.
• onFocus – JavaScript executed when dropdown receives focus. Type: string.
• onBlur – JavaScript executed when dropdown loses focus. Type: string.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs. Type: string.

Security Note: Parsed by cssParser utility. Tenants only affect their own pages (multi‑tenant isolation enforced).

binding

Query‑centric data binding to bind selected value to a field in a query. IMPORTANT: This is SEPARATE from optionsQuery – binding stores the SELECTED VALUE, optionsQuery loads the OPTION LIST. Type: object.

Tip: binding (WHERE to store value) is INDEPENDENT from optionsQuery (WHERE to load option list). A dropdown can have BOTH. Example: State dropdown – optionsQuery loads list of states from ‘states’ query, binding stores selected state code in ‘customer.stateCode’ field.

Sub‑properties:

• query – Name of query defined in root.props.queries (typically a ‘get’ query for editing a single record). Type: string. Required.
• field – Field name in the query to bind to (where selected value is stored). Type: string. Required.
• isReadOnly – Whether dropdown is read‑only (display only, no changes allowed). Type: boolean. Default: false.

Best Practices

• Group Dropdown with related Input fields in Grid/Flex (e.g., Status + Applied On)
• Provide clear option labels that describe the choice
• Set placeholder to guide users (e.g., ‘Select status…’)
• Use required: true for mandatory selections
• Keep option lists reasonable (5‑20 options max) – use search/autocomplete for longer lists
• Use optionsQuery for lookup tables (States, Categories, Products) – more maintainable than hardcoded options
• Use static options array for simple fixed lists (Yes/No, Priority levels, Status values)
• CRITICAL: binding (value storage) is INDEPENDENT from optionsQuery (option list loading)

Common Mistakes

Not grouping Dropdown with related fields in Grid/Flex

Why it's a problem: Dropdown stacked alone at full width wastes space – could be paired with related field

Fix: Group Dropdown with related Input/Date in Grid: Status + Applied On, Category + Priority

Using identical value and label in options

Why it's a problem: Reduces flexibility – better to have clean internal values and user‑friendly labels

Fix: Use { value: 'in_progress', label: 'In Progress' } for better data structure

Too many options (50+) in dropdown

Why it's a problem: Scrolling through long lists is poor UX – hard to find desired option

Fix: Use autocomplete/search component for long lists, keep dropdown for 5‑20 options

Not setting placeholder

Why it's a problem: User doesn’t know what to select or that selection is needed

Fix: Set placeholder: ‘Select status…’ to guide user