import { ArgTypes, Canvas, Markdown, Meta } from '@storybook/addon-docs/blocks';
import { cdnJs } from '../../globals/internal/storybook-cdn';
import * as SelectStories from './select.stories';

<Meta of={SelectStories} />

# Select

[Source code](https://github.com/carbon-design-system/carbon/tree/main/packages/web-components/src/components/select)
&nbsp;|&nbsp;
[Usage guidelines](https://www.carbondesignsystem.com/components/select/usage)
&nbsp;|&nbsp;
[Accessibility](https://www.carbondesignsystem.com/components/select/accessibility)

## Table of Contents

- [Default state](#default-state)
- [Inline](#inline)
- [Skeleton](#skeleton)
- [AI Label](#ai-label)
- [Skeleton](#skeleton)
- [Component API](#component-api)
- [Feedback](#feedback)

## Default state

Carbon recommends that a select has an empty option selected by default.
Depending on the use case, this default behavior can be modified to be a
prefilled selection to the first option in the list, which is typically shown in
alphabetical order, or the prefilled selection could be a frequent or commonly
used option that is on the list.

To get a default empty selection on your select, do not use the `placeholder`
attribute in `cds-select`.

<Canvas of={SelectStories.Default} />

## Inline

<Canvas of={SelectStories.Inline} />

## Skeleton

## Form item

If the select is part of a form, make sure to import and wrap the select with
`<cds-form-item>`

```javascript
import '@carbon/web-components/es/components/form/index.js';
```

<Markdown>{`${cdnJs({ components: ['form'] })}`}</Markdown>

```html
<cds-form-item>
  <cds-select
    helper-text="Optional helper text"
    label-text="Select"
    placeholder="Optional placeholder text">
      <cds-select-item-group label="Category 1">
        <cds-select-item value="all">Option 1</cds-select-item>
        <cds-select-item value="cloudFoundry">Option 2</cds-select-item>
      </cds-select-item-group>
      <cds-select-item-group label="Category 2">
        <cds-select-item value="staging">Option 3</cds-select-item>
        <cds-select-item value="dea">Option 4</cds-select-item>
        <cds-select-item value="router">Option 5</cds-select-item>
      </cds-select-item-group>
  </cds-select>
</cds-form-item>
```

## `<cds-select>` attributes, properties and events
<Canvas of={SelectStories.Skeleton} />

## AI Label

<Canvas of={SelectStories.WithAILabel} />

## Component API

## `cds-select`

<ArgTypes of="cds-select" />

## `cds-select-item-group`

<ArgTypes of="cds-select-item-group" />

## `cds-select-item`

<ArgTypes of="cds-select-item" />

<Markdown>{`${cdnJs({ components: ['select'] })}`}</Markdown>

## Feedback

Help us improve this component by providing feedback, asking questions on Slack,
or updating this file on
[GitHub](https://github.com/carbon-design-system/carbon/edit/main/packages/web-components/src/components/select/select.mdx).
