@vaadin/select/web-types.lit.json

vaadin-select

{
  "$schema": "https://json.schemastore.org/web-types",
  "name": "@vaadin/select",
  "version": "25.0.1",
  "description-markup": "markdown",
  "framework": "lit",
  "framework-config": {
    "enable-when": {
      "node-packages": [
        "lit"
      ]
    }
  },
  "contributions": {
    "html": {
      "elements": [
        {
          "name": "vaadin-select",
          "description": "`<vaadin-select>` is a Web Component for selecting values from a list of items.\n\n### Items\n\nUse the `items` property to define possible options for the select:\n\n```html\n<vaadin-select id=\"select\"></vaadin-select>\n```\n```js\nconst select = document.querySelector('#select');\nselect.items = [\n  { label: 'Most recent first', value: 'recent' },\n  { component: 'hr' },\n  { label: 'Rating: low to high', value: 'rating-asc', className: 'asc' },\n  { label: 'Rating: high to low', value: 'rating-desc', className: 'desc' },\n  { component: 'hr' },\n  { label: 'Price: low to high', value: 'price-asc', disabled: true },\n  { label: 'Price: high to low', value: 'price-desc', disabled: true }\n];\n```\n\n### Rendering\n\nAlternatively, the content of the select can be populated by using the renderer callback function.\n\nThe renderer function provides `root`, `select` arguments.\nGenerate DOM content, append it to the `root` element and control the state\nof the host element by accessing `select`.\n\n```js\nconst select = document.querySelector('#select');\nselect.renderer = function(root, select) {\n  const listBox = document.createElement('vaadin-list-box');\n  // append 3 <vaadin-item> elements\n  ['Jose', 'Manolo', 'Pedro'].forEach(function(name) {\n    const item = document.createElement('vaadin-item');\n    item.textContent = name;\n    item.setAttribute('label', name)\n    listBox.appendChild(item);\n  });\n\n  // update the content\n  root.appendChild(listBox);\n};\n```\n\nRenderer is called on initialization of new select and on its opening.\nDOM generated during the renderer call can be reused\nin the next renderer call and will be provided with the `root` argument.\nOn first call it will be empty.\n\n* Hint: By setting the `label` property of inner vaadin-items you will\nbe able to change the visual representation of the selected value in the input part.\n\n### Styling\n\nThe following custom properties are available for styling:\n\nCustom property                  | Description                 | Default\n---------------------------------|-----------------------------|--------\n`--vaadin-field-default-width`   | Default width of the field  | `12em`\n`--vaadin-select-overlay-width`  | Width of the overlay        |\n\nThe following shadow DOM parts are available for styling:\n\nPart name            | Description\n---------------------|----------------\n`label`              | The label element\n`input-field`        | The element that wraps prefix, value and toggle button\n`field-button`       | Set on the toggle button\n`error-message`      | The error message element\n`helper-text`        | The helper text element wrapper\n`required-indicator` | The `required` state indicator element\n`toggle-button`      | The toggle button\n`backdrop`           | Backdrop of the overlay\n`overlay`            | The overlay container\n`content`            | The overlay content\n\nThe following state attributes are available for styling:\n\nAttribute            | Description\n---------------------|---------------------------------\n`disabled`           | Set when the element is disabled\n`has-value`          | Set when the element has a value\n`has-label`          | Set when the element has a label\n`has-helper`         | Set when the element has helper text or slot\n`has-error-message`  | Set when the element has an error message\n`invalid`            | Set when the element is invalid\n`focused`            | Set when the element is focused\n`focus-ring`         | Set when the element is keyboard focused\n`readonly`           | Set when the element is readonly\n`opened`             | Set when the overlay is opened\n`phone`              | Set when the overlay is shown in phone mode\n\n### Internal components\n\nIn addition to `<vaadin-select>` itself, the following internal\ncomponents are themable:\n\n- `<vaadin-select-value-button>` - has the same API as [`<vaadin-button>`](https://cdn.vaadin.com/vaadin-web-components/25.0.1/#/elements/vaadin-button).\n- `<vaadin-select-list-box>` - has the same API as [`<vaadin-list-box>`](https://cdn.vaadin.com/vaadin-web-components/25.0.1/#/elements/vaadin-list-box).\n- `<vaadin-select-item>` - has the same API as [`<vaadin-item>`](https://cdn.vaadin.com/vaadin-web-components/25.0.1/#/elements/vaadin-item).\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
          "extension": true,
          "attributes": [
            {
              "name": "?disabled",
              "description": "If true, the user cannot interact with this element.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": "?autofocus",
              "description": "Specify that this control should have input focus when the page loads.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": "?invalid",
              "description": "Set to true when the field is invalid.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": "?manualValidation",
              "description": "Set to true to enable manual validation mode. This mode disables automatic\nconstraint validation, allowing you to control the validation process yourself.\nYou can still trigger constraint validation manually with the `validate()` method\nor use `checkValidity()` to assess the component's validity without affecting\nthe invalid state. In manual validation mode, you can also manipulate\nthe `invalid` property directly through your application logic without conflicts\nwith the component's internal validation.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": "?required",
              "description": "Specifies that the user must fill in a value.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": "?opened",
              "description": "Set when the select is open",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": "?readonly",
              "description": "When present, it specifies that the element is read-only.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": "?noVerticalOverlap",
              "description": "Defines whether the overlay should overlap the target element\nin the y-axis, or be positioned right above/below it.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": ".label",
              "description": "The label text for the input node.\nWhen no light dom defined via [slot=label], this value will be used.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": ".errorMessage",
              "description": "Error to show when the field is invalid.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": ".helperText",
              "description": "String used for the helper text.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": ".accessibleName",
              "description": "String used to label the component to screen reader users.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": ".accessibleNameRef",
              "description": "Id of the element used as label of the component to screen reader users.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": ".items",
              "description": "An array containing items that will be rendered as the options of the select.\n\n#### Example\n```js\nselect.items = [\n  { label: 'Most recent first', value: 'recent' },\n  { component: 'hr' },\n  { label: 'Rating: low to high', value: 'rating-asc', className: 'asc' },\n  { label: 'Rating: high to low', value: 'rating-desc', className: 'desc' },\n  { component: 'hr' },\n  { label: 'Price: low to high', value: 'price-asc', disabled: true },\n  { label: 'Price: high to low', value: 'price-desc', disabled: true }\n];\n```\n\nNote: each item is rendered by default as the internal `<vaadin-select-item>` that is an extension of `<vaadin-item>`.\nTo render the item with a custom component, provide a tag name by the `component` property.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": ".renderer",
              "description": "Custom function for rendering the content of the `<vaadin-select>`.\nReceives two arguments:\n\n- `root` The internal container DOM element. Append your content to it.\n- `select` The reference to the `<vaadin-select>` element.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": ".value",
              "description": "The `value` property of the selected item, or an empty string\nif no item is selected.\nOn change or initialization, the component finds the item which matches the\nvalue and displays it.\nIf no value is provided to the component, it selects the first item without\nvalue or empty value.\nHint: If you do not want to select any item by default, you can either set all\nthe values of inner vaadin-items, or set the vaadin-select value to\nan inexistent value in the items list.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": ".name",
              "description": "The name of this element.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": ".placeholder",
              "description": "A hint to the user of what can be entered in the control.\nThe placeholder will be displayed in the case that there\nis no item selected, or the selected item has an empty\nstring label, or the selected item has no label and it's\nDOM content is empty.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": "@validated",
              "description": "Fired whenever the field is validated.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": "@change",
              "description": "Fired when the user commits a value change.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": "@invalid-changed",
              "description": "Fired when the `invalid` property changes.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": "@opened-changed",
              "description": "Fired when the `opened` property changes.",
              "value": {
                "kind": "expression"
              }
            },
            {
              "name": "@value-changed",
              "description": "Fired when the `value` property changes.",
              "value": {
                "kind": "expression"
              }
            }
          ]
        }
      ]
    }
  }
}