You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A modern, accessible combobox component for Vue applications.
4
+
5
+
<ComboboxDemo />
6
+
7
+
## Features
8
+
9
+
- 🎯 Fully accessible (WAI-ARIA compliant)
10
+
- 🌐 Keyboard navigation support
11
+
- 🎨 Customizable styling
12
+
- 🔄 Dynamic filtering
13
+
- 📱 Mobile-friendly
14
+
- 🎯 TypeScript support
15
+
6
16
<br>
7
17
8
-
# Install
18
+
##Install
9
19
10
20
::: code-group
11
21
@@ -30,32 +40,34 @@ yarn add @stacksjs/combobox
30
40
```
31
41
32
42
:::
33
-
34
43
<br>
35
44
36
-
# Usage
37
-
38
-
`Comboboxes` are built using the `Combobox`, `ComboboxInput`, `ComboboxOptions`, `ComboboxOption` and `ComboboxLabel` components.
39
-
40
-
The `ComboboxInput` will automatically open/close the `ComboboxOptions` when searching.
45
+
## Usage
41
46
42
-
You are completely in charge of how you filter the results, whether it be with a fuzzy search library client-side or by making server-side requests to an API. In this example we will keep the logic simple for demo purposes.
47
+
The combobox component is composed of several sub-components that work together to create a fully functional and accessible combobox:
43
48
44
49
```vue
45
-
<script lang="ts" setup>
46
-
import { Combobox, ComboboxInput, ComboboxOptions, ComboboxOption } from '@stacksjs/combobox'
<ComboboxOption v-for="item in items" :key="item.id" :value="item">
70
+
{{ item.name }}
59
71
</ComboboxOption>
60
72
</ComboboxOptions>
61
73
</Combobox>
@@ -64,8 +76,108 @@ You are completely in charge of how you filter the results, whether it be with a
64
76
65
77
<br>
66
78
67
-
#Demo
79
+
## API Reference
68
80
69
-
<ComboboxDemo />
81
+
### Combobox
82
+
83
+
The root component that wraps all combobox elements.
84
+
85
+
#### Props
86
+
87
+
-`v-model` - The selected value(s)
88
+
-`disabled` - (boolean) Whether the combobox is disabled
89
+
-`as` - (string) The element to render as (default: 'template')
90
+
91
+
### ComboboxInput
92
+
93
+
The input element of the combobox.
94
+
95
+
#### Props
96
+
97
+
-`displayValue` - (Function) Function to format the display value
98
+
-`placeholder` - (string) Input placeholder text
99
+
100
+
#### Events
101
+
102
+
-`@change` - Emitted when the input value changes
103
+
-`@focus` - Emitted when the input receives focus
104
+
-`@blur` - Emitted when the input loses focus
105
+
106
+
### ComboboxButton
107
+
108
+
The button that toggles the combobox options.
109
+
110
+
#### Props
111
+
112
+
-`as` - (string) The element to render as (default: 'button')
113
+
114
+
### ComboboxOptions
115
+
116
+
The container for the list of options.
117
+
118
+
#### Props
119
+
120
+
-`as` - (string) The element to render as (default: 'ul')
121
+
-`static` - (boolean) Whether the options should always be rendered
122
+
-`hold` - (boolean) Whether to maintain the options in the DOM when hidden
123
+
124
+
### ComboboxOption
125
+
126
+
Individual option items within the combobox.
127
+
128
+
#### Props
129
+
130
+
-`value` - The value associated with the option
131
+
-`disabled` - (boolean) Whether the option is disabled
132
+
-`as` - (string) The element to render as (default: 'li')
133
+
134
+
#### Slot Props
135
+
136
+
The ComboboxOption component exposes the following slot props:
137
+
138
+
-`active` - (boolean) Whether the option is currently active (focused)
139
+
-`selected` - (boolean) Whether the option is currently selected
140
+
-`disabled` - (boolean) Whether the option is disabled
141
+
142
+
## Styling
143
+
144
+
The combobox components can be styled using standard CSS classes. Each component accepts standard HTML attributes including `class` and `style`.
145
+
146
+
For dynamic styling based on state, use the slot props provided by ComboboxOption:
147
+
148
+
```vue
149
+
<ComboboxOption v-slot="{ active, selected }">
150
+
<li :class="{
151
+
'bg-blue-500 text-white': active,
152
+
'bg-white text-black': !active,
153
+
'font-bold': selected
154
+
}">
155
+
{{ option.name }}
156
+
</li>
157
+
</ComboboxOption>
158
+
```
159
+
160
+
## Accessibility
161
+
162
+
The combobox component follows WAI-ARIA guidelines and includes the following features:
163
+
164
+
- Full keyboard navigation support
165
+
- ARIA attributes automatically managed
166
+
- Screen reader announcements for selection changes
167
+
- Focus management
168
+
169
+
## TypeScript Support
170
+
171
+
The combobox component includes full TypeScript support. You can specify the type of your items:
172
+
173
+
```ts
174
+
interfaceItem {
175
+
id:number
176
+
name:string
177
+
}
178
+
179
+
const selected =ref<Item|null>(null)
180
+
const items =ref<Item[]>([])
181
+
```
70
182
71
183
Still have questions relating this component’s usage? Contact us and we will help you out. In the meantime, if you are curious about the [`<CommandPalette />`](./command-palette.md) component read more on the next page.
0 commit comments