Dropdown Options

Many of the dropdown-style components in Tyler Forge™, such as the autocomplete and menu for example, are configured using an array of JavaScript objects that describe the options that should be rendered to the user. This allows for a high degree of customization and flexibility when it comes to the content and behavior of the dropdown, while also making it easier to manage the data that is displayed.

With that said, sometimes it can be difficult to understand how to configure these dropdowns, especially when it comes to more complex scenarios. This guide will help you understand how to configure options in various ways, while also showing example of how to use what we call “builder” callbacks to provide your own custom content and overrides for the options.

List Items

The “options” you see rendered within a dropdwon are just <forge-list-item> components that are rendered within a <forge-list> component. This means that you can use the same configuration options that are available to the <forge-list-item> component to customize the appearance and behavior of the options that are rendered in the dropdown.

Keep this in mind for below when we discuss the builder callbacks because an instance of the list item component is created for each option that is rendered in the dropdown, and it is provided as an argument to the builder callback so that you can further control the list item if necessary.

Configuration

The configuration of dropdown options is typically done using an array of JavaScript objects that describe the options that should be rendered in the dropdown. Each object in the array represents an option that the user can select, and typically contains properties such as label, value, and disabled (among many others) to control the appearance and behavior of the option.

The interfaces below are an example of all of the configuration properties that are available to you at a base level:

interface IBaseListDropdownOption<T = any> {
  value: T; // The underlying value
  label: string; // The primary text
  secondaryLabel?: string; // Secondary supporting text (optional)
  disabled?: boolean; // Whether the option is disabled
  divider?: boolean; // Options can be just a divider to separate groups of options
  optionClass?: string | string[]; // Custom CSS classes to apply to the option
  leadingIcon?: string; // Leading icon name
  leadingIconClass?: string; // Custom CSS classes to apply to the leading icon
  leadingIconType?: ListDropdownIconType; // Icon type, font (default) or component (renders a <forge-icon>).
  leadingIconComponentProps?: Partial<IIconComponent>; // Props to pass to the leading icon component (only pertains when the leading icon type is "component")
  trailingIcon?: string; // Trailing icon name
  trailingIconClass?: string; // Custom CSS classes to apply to the trailing icon
  trailingIconType?: ListDropdownIconType; // Icon type, font (default) or component (renders a <forge-icon>).
  trailingIconComponentProps?: Partial<IIconComponent>; // Props to pass to the trailing icon component (only pertains when the trailing icon type is "component")
  leadingBuilder?: () => HTMLElement; // Allows for providing a custom content in the leading area of the option
  trailingBuilder?: () => HTMLElement; // Allows for providing a custom content in the trailing area of the option
  tooltip?: ListDropdownTooltipConfig; // Tooltip configuration
}

interface IListDropdownOption<T = any> extends IBaseListDropdownOption<T> {
  options?: Array<IListDropdownOption | IListDropdownOptionGroup>; // Nested options (can be a flat list of options or a group of options with header labels)
  elementAttributes?: Map<string, string>; // Attributes to apply to the option (<forge-list-item>)
}

The interface is the base configuration that is used for all dropdown-style components in Tyler Forge™. However, each dropdown component may have additional properties that are specific to that component. See below for information on how to configure options for each dropdown component:

Menu

The menu component provides a few additional configuration options that are specific to the menu component:

interface IMenuOption<T = any> extends IListDropdownOption<T> {
  icon?: string; // A convenience property for setting the leading icon
  selected?: boolean; // Whether the option is selected
}

Builder Callbacks

Builder callbacks are a way to provide your own custom content and overrides for the options that are rendered in the dropdown. This concept is commonly known as “render props” in various frameworks out there. It essentially allows for you to hook into the rendering process of the options and provide your own custom content or behavior for each option that is rendered (to an extent).

See below for an example of how to use builder callbacks to provide your own custom content for the options that are rendered in the dropdown:

// The type for the builder callback will be specific to the component.
// Below is an example that pertains to the `<forge-menu>` component.
const optionBuilder: MenuOptionBuilder = (option, listItem) => {
  // You can modify the `<forge-list-item>` here if necessary via the `listItem` argument
  listItem.setAttribute('data-custom-attribute', 'custom-value');

  // You can return either a string (which overrides the option label) or an HTML element
  const span = document.createElement('span');
  span.style.color = 'red';
  span.textContent = `Custom label: ${option.label}`;
  return span;
};

Example

Below is an example of how you might configure menu options using various properties such as leading icons, secondary text, and tooltips:

const options: IMenuOption[] = [
  {
    label: 'Settings',
    secondaryLabel: 'Settings for your account',
    value: 'settings',
    leadingIcon: 'settings',
    leadingIconType: 'component',
    tooltip: { text: 'View user settings', type: 'label' }
  },
  {
    label: 'Help',
    secondaryLabel: 'Get help with the application',
    value: 'help',
    leadingIcon: 'help',
    leadingIconType: 'component',
    tooltip: { text: 'View help information', type: 'label' }
  }
];

Declarative Configuration

The select component is a good example of a dropdown-style component that uses a declarative configuration to define the options that should be displayed to the user. The child <forge-option> elements are just configuration. However, this is just syntax sugar for the underlying JavaScript objects configuration that is used to render the options.

A caveat with this pattern is that if you were to place any HTML within the <forge-option> elements, it would be rendered as text and not as HTML. This is because the <forge-option> elements are just configuration and not actual HTML elements that get rendered in the dropdown…

Future Improvements

Now that the native HTML Popover API is available and used to power the <forge-popover>, we have the opportunity to actually render the <forge-option> elements, and any HTML specified within their content, verbatim in the dropdown. This will be a huge improvement over the current pattern, and greatly simplify the configuration and usage of all dropdown-style components within Forge.

We expect to begin work on implementing this change in the second half of 2025, so stay tuned for updates on this exciting new feature!