{
  "_copyright": "Copyright (c) 2026, Salesforce, Inc., All rights reserved. For full license text, see the LICENSE.txt file",
  "$schema": "https://slds.lightningdesignsystem.com/schemas/uif-foundation.v1.json",
  "apiVersion": "1.0.0",
  "name": "Combobox",
  "description": "A widget that provides a user with an input field that is either an autocomplete or readonly, accompanied with a listbox of pre-defined options.",
  "structure": {
    "name": "root",
    "restrict": [
      "div"
    ],
    "description": "Combobox form-element container",
    "children": [
      {
        "name": "label",
        "restrict": [
          "label"
        ],
        "description": "Combobox label",
        "slot": {
          "name": "label",
          "required": true
        }
      },
      {
        "name": "formElement",
        "restrict": [
          "div"
        ],
        "description": "Form-element control wrapper that hosts the combobox and its companion regions",
        "children": [
          {
            "name": "group",
            "restrict": [
              "div"
            ],
            "description": "Optional outer wrapper that pairs an object-switcher addon with the primary combobox. Renders only when the consumer opts into the grouped layout.",
            "children": [
              {
                "name": "groupAddonStart",
                "restrict": [
                  "div"
                ],
                "description": "Leading addon that hosts a secondary combobox used to scope or filter what the primary combobox searches over"
              },
              {
                "name": "groupAddonEnd",
                "restrict": [
                  "div"
                ],
                "description": "Trailing addon that hosts the primary combobox"
              }
            ]
          },
          {
            "name": "container",
            "restrict": [
              "div"
            ],
            "description": "Combobox container wrapper (default layout, and also reused inside each grouped addon)",
            "children": [
              {
                "name": "objectSwitcherButton",
                "restrict": [
                  "div"
                ],
                "description": "Deprecated multi-entity object-switcher button rendered as a sibling of the combobox inside the container",
                "children": [
                  {
                    "name": "objectSwitcherTrigger",
                    "restrict": [
                      "button"
                    ],
                    "description": "Trigger that opens the object-switcher menu",
                    "attributes": {
                      "static": {
                        "aria-haspopup": "true"
                      }
                    },
                    "children": [
                      {
                        "name": "objectSwitcherTriggerIcon",
                        "restrict": [
                          "span"
                        ],
                        "description": "Icon representing the currently scoped entity"
                      },
                      {
                        "name": "objectSwitcherTriggerCaret",
                        "restrict": [
                          "svg"
                        ],
                        "description": "Down-caret indicating the trigger opens a menu"
                      }
                    ]
                  }
                ]
              },
              {
                "name": "combobox",
                "restrict": [
                  "div"
                ],
                "description": "Combobox input wrapper",
                "attributes": {
                  "bound": {
                    "aria-expanded": {
                      "prop": "isOpen"
                    },
                    "aria-haspopup": {
                      "prop": "popupType"
                    }
                  }
                },
                "children": [
                  {
                    "name": "inputWrapper",
                    "restrict": [
                      "div"
                    ],
                    "description": "Wrapper around the text input and any leading/trailing icons",
                    "attributes": {
                      "static": {
                        "role": "none"
                      }
                    },
                    "children": [
                      {
                        "name": "inputEntityIcon",
                        "restrict": [
                          "span"
                        ],
                        "description": "Leading entity icon shown when a value is selected (inline-listbox and lookup-selected layouts)",
                        "renderWhen": "propFilled"
                      },
                      {
                        "name": "inputIconLeft",
                        "restrict": [
                          "span"
                        ],
                        "description": "Generic leading icon (search, scoping glyph, etc.)",
                        "renderWhen": "propFilled"
                      },
                      {
                        "name": "input",
                        "restrict": [
                          "input"
                        ],
                        "description": "Editable text input. The role=combobox lives here for autocomplete / typeahead layouts.",
                        "attributes": {
                          "static": {
                            "type": "text",
                            "autocomplete": "off",
                            "role": "combobox"
                          },
                          "bound": {
                            "aria-controls": {
                              "prop": "popupId"
                            },
                            "aria-expanded": {
                              "prop": "isOpen"
                            },
                            "aria-haspopup": {
                              "prop": "popupType"
                            },
                            "aria-autocomplete": {
                              "prop": "autocompleteMode"
                            },
                            "aria-activedescendant": {
                              "prop": "activeOptionId"
                            }
                          }
                        }
                      },
                      {
                        "name": "inputFaux",
                        "restrict": [
                          "div"
                        ],
                        "description": "Read-only faux-input display used by select-only and dialog comboboxes. The role=combobox lives here.",
                        "renderWhen": {
                          "prop": "mode",
                          "eq": "selectOnly"
                        },
                        "attributes": {
                          "static": {
                            "role": "combobox",
                            "tabindex": "0"
                          },
                          "bound": {
                            "aria-controls": {
                              "prop": "popupId"
                            },
                            "aria-expanded": {
                              "prop": "isOpen"
                            },
                            "aria-haspopup": {
                              "prop": "popupType"
                            },
                            "aria-labelledby": {
                              "prop": "labelId"
                            }
                          }
                        },
                        "children": [
                          {
                            "name": "inputFauxValue",
                            "restrict": [
                              "span"
                            ],
                            "description": "Text label of the currently displayed value"
                          }
                        ]
                      },
                      {
                        "name": "inputIconRight",
                        "restrict": [
                          "span"
                        ],
                        "description": "Trailing icon (caret, search, etc.) shown beside the input"
                      },
                      {
                        "name": "inputRemoveButton",
                        "restrict": [
                          "button"
                        ],
                        "description": "Trailing 'remove selected option' button shown when a value is set in lookup layouts",
                        "renderWhen": {
                          "prop": "showRemove",
                          "eq": "true"
                        }
                      },
                      {
                        "name": "inputIconGroup",
                        "restrict": [
                          "div"
                        ],
                        "description": "Trailing affordance group that stacks a loading spinner alongside a remove button (typeahead-loading layouts)",
                        "renderWhen": {
                          "prop": "showInputIconGroup",
                          "eq": "true"
                        }
                      }
                    ]
                  },
                  {
                    "name": "listbox",
                    "restrict": [
                      "div"
                    ],
                    "description": "Listbox dropdown panel hosting selectable options. Mutually exclusive with the popover dialog variant.",
                    "renderWhen": {
                      "prop": "dropdownType",
                      "eq": "listbox"
                    },
                    "attributes": {
                      "static": {
                        "role": "listbox"
                      },
                      "bound": {
                        "aria-busy": {
                          "prop": "isLoading"
                        }
                      }
                    },
                    "children": [
                      {
                        "name": "listboxList",
                        "restrict": [
                          "ul"
                        ],
                        "description": "Inner list element. Carries role=presentation in flat lists and role=group when the listbox is segmented.",
                        "children": [
                          {
                            "name": "listboxItem",
                            "restrict": [
                              "li"
                            ],
                            "description": "Listbox row wrapper",
                            "repeats": true,
                            "children": [
                              {
                                "name": "listboxOption",
                                "restrict": [
                                  "div"
                                ],
                                "description": "Option content rendered as a media object (icon + body)",
                                "attributes": {
                                  "static": {
                                    "role": "option"
                                  },
                                  "bound": {
                                    "aria-selected": {
                                      "prop": "isSelected"
                                    }
                                  }
                                },
                                "children": [
                                  {
                                    "name": "optionFigure",
                                    "restrict": [
                                      "span"
                                    ],
                                    "description": "Leading figure cell that holds an option icon or a 'selected' check",
                                    "children": [
                                      {
                                        "name": "optionIconContainer",
                                        "restrict": [
                                          "span"
                                        ],
                                        "description": "Wrapper around the option's sprite icon",
                                        "children": [
                                          {
                                            "name": "optionIconSvg",
                                            "restrict": [
                                              "svg"
                                            ],
                                            "description": "Sprite icon"
                                          }
                                        ]
                                      },
                                      {
                                        "name": "optionSelectedSvg",
                                        "restrict": [
                                          "svg"
                                        ],
                                        "description": "Inline 'selected' check rendered directly inside the figure (deprecated readonly variant)",
                                        "renderWhen": {
                                          "prop": "showInlineSelectedCheck",
                                          "eq": "true"
                                        }
                                      }
                                    ]
                                  },
                                  {
                                    "name": "optionBody",
                                    "restrict": [
                                      "span"
                                    ],
                                    "description": "Body cell that holds the primary text and optional metadata",
                                    "children": [
                                      {
                                        "name": "optionText",
                                        "restrict": [
                                          "span"
                                        ],
                                        "description": "Primary text line",
                                        "children": [
                                          {
                                            "name": "optionTextHighlight",
                                            "restrict": [
                                              "mark"
                                            ],
                                            "description": "Highlighted match fragment inside the option text (typeahead)",
                                            "renderWhen": "propFilled"
                                          }
                                        ]
                                      },
                                      {
                                        "name": "optionMeta",
                                        "restrict": [
                                          "span"
                                        ],
                                        "description": "Secondary metadata line on entity options",
                                        "renderWhen": "propFilled"
                                      }
                                    ]
                                  },
                                  {
                                    "name": "optionHeader",
                                    "restrict": [
                                      "h3"
                                    ],
                                    "description": "Group / section heading rendered in place of an option's body",
                                    "renderWhen": {
                                      "prop": "kind",
                                      "eq": "header"
                                    },
                                    "attributes": {
                                      "static": {
                                        "role": "presentation"
                                      }
                                    }
                                  }
                                ]
                              }
                            ],
                            "slot": {
                              "name": "options",
                              "required": true
                            }
                          },
                          {
                            "name": "loadingItem",
                            "restrict": [
                              "li"
                            ],
                            "description": "Row appended to the bottom of the listbox while results are streaming in",
                            "renderWhen": {
                              "prop": "loading",
                              "eq": "true"
                            },
                            "children": [
                              {
                                "name": "loadingItemSpinner",
                                "restrict": [
                                  "div"
                                ],
                                "description": "Spinner control announcing 'loading' to assistive tech",
                                "attributes": {
                                  "static": {
                                    "role": "status"
                                  }
                                }
                              }
                            ]
                          }
                        ]
                      }
                    ]
                  },
                  {
                    "name": "popover",
                    "restrict": [
                      "section"
                    ],
                    "description": "Dialog popover dropdown hosting arbitrary content in place of a listbox (e.g., a checkbox group)",
                    "renderWhen": {
                      "prop": "dropdownType",
                      "eq": "dialog"
                    },
                    "attributes": {
                      "static": {
                        "role": "dialog"
                      },
                      "bound": {
                        "aria-describedby": {
                          "prop": "popoverBodyId"
                        },
                        "aria-label": {
                          "prop": "popoverLabel"
                        }
                      }
                    },
                    "children": [
                      {
                        "name": "popoverBody",
                        "restrict": [
                          "div"
                        ],
                        "description": "Scrollable region of the popover",
                        "attributes": {
                          "static": {
                            "role": "region",
                            "tabindex": "0"
                          }
                        },
                        "slot": {
                          "name": "popoverBody",
                          "required": true
                        }
                      },
                      {
                        "name": "popoverFooter",
                        "restrict": [
                          "footer"
                        ],
                        "description": "Action row at the bottom of the popover (e.g., Cancel + Done)",
                        "slot": {
                          "name": "popoverFooter"
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "name": "selectionGroup",
            "restrict": [
              "div"
            ],
            "description": "Region rendered alongside the combobox that displays selected options as removable pills",
            "renderWhen": {
              "prop": "showSelectionPills",
              "eq": "true"
            },
            "children": [
              {
                "name": "selectionToggle",
                "restrict": [
                  "span"
                ],
                "description": "Optional 'show more' affordance that reveals the rest of the pill list",
                "renderWhen": "propFilled",
                "attributes": {
                  "static": {
                    "aria-hidden": "true"
                  }
                },
                "children": [
                  {
                    "name": "selectionToggleButton",
                    "restrict": [
                      "button"
                    ],
                    "description": "Button that toggles the collapsed/expanded state of the pill list"
                  }
                ]
              },
              {
                "name": "selectionPillsList",
                "restrict": [
                  "ul"
                ],
                "description": "Horizontal list of selected-option pills",
                "attributes": {
                  "bound": {
                    "aria-label": {
                      "prop": "selectionListLabel"
                    }
                  }
                },
                "children": [
                  {
                    "name": "selectionPillItem",
                    "restrict": [
                      "li"
                    ],
                    "description": "Pill list row",
                    "repeats": true,
                    "children": [
                      {
                        "name": "selectionPill",
                        "restrict": [
                          "span"
                        ],
                        "description": "Pill representing one selected option",
                        "children": [
                          {
                            "name": "selectionPillIcon",
                            "restrict": [
                              "span"
                            ],
                            "description": "Leading entity icon",
                            "renderWhen": "propFilled"
                          },
                          {
                            "name": "selectionPillLabel",
                            "restrict": [
                              "span"
                            ],
                            "description": "Pill text label"
                          },
                          {
                            "name": "selectionPillRemove",
                            "restrict": [
                              "span"
                            ],
                            "description": "Wrapper around the remove-pill button",
                            "children": [
                              {
                                "name": "selectionPillRemoveButton",
                                "restrict": [
                                  "button"
                                ],
                                "description": "Button that removes the option from the selection"
                              }
                            ]
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "states": [
    {
      "name": "open",
      "type": "boolean",
      "aria": "aria-expanded",
      "description": "Whether dropdown is open"
    },
    {
      "name": "disabled",
      "type": "boolean",
      "aria": "aria-disabled",
      "description": "Whether combobox is disabled"
    },
    {
      "name": "required",
      "type": "boolean",
      "aria": "aria-required",
      "description": "Whether selection is required"
    },
    {
      "name": "hasError",
      "type": "boolean",
      "description": "Whether the combobox has a validation error"
    },
    {
      "name": "loading",
      "type": "boolean",
      "aria": "aria-busy",
      "description": "Whether the combobox is loading results"
    },
    {
      "name": "focused",
      "type": "boolean",
      "description": "Whether the combobox input has focus"
    },
    {
      "name": "expanded",
      "type": "boolean",
      "description": "Whether the combobox is rendered in its expanded shape (used by deprecated multi-entity layouts)"
    }
  ],
  "accessibility": {
    "requirements": [
      {
        "id": "combobox-role",
        "description": "Input wrapper or faux-input element must carry role='combobox'"
      },
      {
        "id": "listbox-role",
        "description": "Listbox dropdown must carry role='listbox'"
      },
      {
        "id": "dialog-role",
        "description": "Dialog dropdown must carry role='dialog' and an accessible label"
      },
      {
        "id": "keyboard-navigation",
        "description": "Arrow keys navigate options, Enter selects, Escape closes"
      },
      {
        "id": "live-loading-status",
        "description": "Loading rows announce 'loading' via role='status'"
      }
    ]
  }
}