Skip to content

docs(picker): updated docs with allowed menu content #5446

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
May 7, 2025
Merged

docs(picker): updated docs with allowed menu content #5446

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4194208
docs(picker): updated docs with allowed menu content
nikkimk May 6, 2025
42cbf31
docs(picker): fixed types
nikkimk May 6, 2025
9dc004d
Merge branch 'main' into nikkimk/picker-group-submenu-docs
nikkimk May 6, 2025
261d866
docs(picker): fixed typo
nikkimk May 6, 2025
d9f8121
docs(picker): fixed typos
nikkimk May 6, 2025
1463cad
Merge branch 'main' into nikkimk/picker-group-submenu-docs
nikkimk May 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions packages/picker/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,8 @@ import { Picker } from '@spectrum-web-components/picker';

### Anatomy

A picker includes a label and a menu.

#### Labels

To render accessibly, an `<sp-picker>` element should be paired with an `<sp-field-label>` element that has the `for` attribute referencing the `id` of the `<sp-picker>` element.
Expand Down Expand Up @@ -91,6 +93,32 @@ For an accessible label that renders within the bounds of the picker itself, but
</sp-tab-panel>
</sp-tabs>

#### Menu

The picker menu is a menu element that is used to display the options for the picker. A picker menu can include menu items, menu dividers, and menu groups. A picker menu should never contain submenus, as doing so would render it inaccessible.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Notes that submenus would make a picker inaccessible.


If you require a submenu, use and [action menu](./action-menu) instead of a picker.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎶 I loveeeeee this so much


```html demo
<sp-picker>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Example with menu groups since picker can accept them.

<span slot="label">Select a free food item:</span>
<sp-menu-group>
<span slot="header">Fruits</span>
<sp-menu-item>Apple</sp-menu-item>
<sp-menu-item>Banana</sp-menu-item>
<sp-menu-item>Pear</sp-menu-item>
</sp-menu-group>
<sp-menu-divider></sp-menu-divider>
<sp-menu-group>
<span slot="header">Vegetables</span>
<sp-menu-item>Artichoke</sp-menu-item>
<sp-menu-item>Carrot</sp-menu-item>
<sp-menu-item>Potato</sp-menu-item>
</sp-menu-group>
<sp-menu-group>
</sp-picker>
```

#### Icons

`<sp-menu-item>`s in an `<sp-picker>` that are provided content addressed to their `icon` slot will be passed to the `<sp-picker>` element when that item is chosen.
Expand Down Expand Up @@ -660,3 +688,7 @@ Use [`<sp-help-text>`](../help-text/) to add help text and error text:

</sp-tab-panel>
</sp-tabs>

#### Do not use submenus

A picker menu should never contain submenus, as doing so would render it inaccessible. A picker's menu role is a listbox, and its menu items are listbox options, which are not allowed to have submenus.
Loading