@xsolla/xui-select 0.99.0 → 0.100.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +332 -19
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,39 +1,352 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
title: Select
|
|
3
|
+
subtitle: A dropdown select for predefined options.
|
|
4
|
+
description: A cross-platform React select component for choosing from a list of predefined options with dropdown menu.
|
|
5
|
+
---
|
|
2
6
|
|
|
3
|
-
|
|
7
|
+
# Select
|
|
8
|
+
|
|
9
|
+
A cross-platform React select component for choosing from a list of predefined options with dropdown menu. Works on both React (web) and React Native.
|
|
4
10
|
|
|
5
11
|
## Installation
|
|
6
12
|
|
|
7
13
|
```bash
|
|
14
|
+
npm install @xsolla/xui-select
|
|
15
|
+
# or
|
|
8
16
|
yarn add @xsolla/xui-select
|
|
9
17
|
```
|
|
10
18
|
|
|
11
|
-
##
|
|
19
|
+
## Demo
|
|
20
|
+
|
|
21
|
+
### Basic Select
|
|
22
|
+
|
|
23
|
+
```tsx
|
|
24
|
+
import * as React from 'react';
|
|
25
|
+
import { Select } from '@xsolla/xui-select';
|
|
26
|
+
|
|
27
|
+
export default function BasicSelect() {
|
|
28
|
+
const [value, setValue] = React.useState('');
|
|
29
|
+
|
|
30
|
+
return (
|
|
31
|
+
<Select
|
|
32
|
+
value={value}
|
|
33
|
+
onChange={setValue}
|
|
34
|
+
options={['Option 1', 'Option 2', 'Option 3']}
|
|
35
|
+
placeholder="Select an option"
|
|
36
|
+
/>
|
|
37
|
+
);
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Select with Label
|
|
42
|
+
|
|
43
|
+
```tsx
|
|
44
|
+
import * as React from 'react';
|
|
45
|
+
import { Select } from '@xsolla/xui-select';
|
|
46
|
+
|
|
47
|
+
export default function LabeledSelect() {
|
|
48
|
+
const [country, setCountry] = React.useState('');
|
|
49
|
+
|
|
50
|
+
return (
|
|
51
|
+
<Select
|
|
52
|
+
label="Country"
|
|
53
|
+
value={country}
|
|
54
|
+
onChange={setCountry}
|
|
55
|
+
options={['United States', 'Canada', 'United Kingdom', 'Germany', 'France']}
|
|
56
|
+
placeholder="Select a country"
|
|
57
|
+
/>
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Select with Object Options
|
|
63
|
+
|
|
64
|
+
```tsx
|
|
65
|
+
import * as React from 'react';
|
|
66
|
+
import { Select } from '@xsolla/xui-select';
|
|
67
|
+
|
|
68
|
+
export default function ObjectOptionsSelect() {
|
|
69
|
+
const [status, setStatus] = React.useState('');
|
|
70
|
+
|
|
71
|
+
const options = [
|
|
72
|
+
{ label: 'Active', value: 'active' },
|
|
73
|
+
{ label: 'Pending', value: 'pending' },
|
|
74
|
+
{ label: 'Inactive', value: 'inactive' },
|
|
75
|
+
];
|
|
76
|
+
|
|
77
|
+
return (
|
|
78
|
+
<Select
|
|
79
|
+
label="Status"
|
|
80
|
+
value={status}
|
|
81
|
+
onChange={setStatus}
|
|
82
|
+
options={options}
|
|
83
|
+
placeholder="Select status"
|
|
84
|
+
/>
|
|
85
|
+
);
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### Select Sizes
|
|
12
90
|
|
|
13
91
|
```tsx
|
|
92
|
+
import * as React from 'react';
|
|
93
|
+
import { Select } from '@xsolla/xui-select';
|
|
94
|
+
|
|
95
|
+
export default function SelectSizes() {
|
|
96
|
+
const options = ['Small', 'Medium', 'Large'];
|
|
97
|
+
|
|
98
|
+
return (
|
|
99
|
+
<div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
|
|
100
|
+
<Select size="xs" options={options} placeholder="Extra Small" />
|
|
101
|
+
<Select size="sm" options={options} placeholder="Small" />
|
|
102
|
+
<Select size="md" options={options} placeholder="Medium (default)" />
|
|
103
|
+
<Select size="lg" options={options} placeholder="Large" />
|
|
104
|
+
<Select size="xl" options={options} placeholder="Extra Large" />
|
|
105
|
+
</div>
|
|
106
|
+
);
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Select with Icons
|
|
111
|
+
|
|
112
|
+
```tsx
|
|
113
|
+
import * as React from 'react';
|
|
114
|
+
import { Select } from '@xsolla/xui-select';
|
|
115
|
+
import { Globe } from '@xsolla/xui-icons-base';
|
|
116
|
+
|
|
117
|
+
export default function SelectWithIcons() {
|
|
118
|
+
return (
|
|
119
|
+
<Select
|
|
120
|
+
iconLeft={<Globe />}
|
|
121
|
+
options={['English', 'Spanish', 'French', 'German']}
|
|
122
|
+
placeholder="Select language"
|
|
123
|
+
/>
|
|
124
|
+
);
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## Anatomy
|
|
129
|
+
|
|
130
|
+
Import the component and use it directly:
|
|
131
|
+
|
|
132
|
+
```jsx
|
|
14
133
|
import { Select } from '@xsolla/xui-select';
|
|
15
134
|
|
|
16
135
|
<Select
|
|
17
|
-
label="
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
136
|
+
label="Field Label" // Optional label above select
|
|
137
|
+
value={value} // Controlled selected value
|
|
138
|
+
onChange={setValue} // Value change handler
|
|
139
|
+
options={['A', 'B', 'C']} // Array of options (strings or objects)
|
|
140
|
+
placeholder="Select..." // Placeholder text
|
|
141
|
+
iconLeft={<Icon />} // Optional left icon
|
|
142
|
+
iconRight={<Icon />} // Optional right icon (default: ChevronDown)
|
|
143
|
+
filled // Whether to show filled background
|
|
144
|
+
state="error" // State: "default" | "disable" | "error"
|
|
145
|
+
errorMessage="Error message" // Error message (shown when state="error")
|
|
21
146
|
/>
|
|
22
147
|
```
|
|
23
148
|
|
|
24
|
-
##
|
|
149
|
+
## Examples
|
|
150
|
+
|
|
151
|
+
### Error State
|
|
152
|
+
|
|
153
|
+
```tsx
|
|
154
|
+
import * as React from 'react';
|
|
155
|
+
import { Select } from '@xsolla/xui-select';
|
|
156
|
+
|
|
157
|
+
export default function ErrorSelect() {
|
|
158
|
+
return (
|
|
159
|
+
<Select
|
|
160
|
+
label="Required Field"
|
|
161
|
+
state="error"
|
|
162
|
+
errorMessage="Please select an option"
|
|
163
|
+
options={['Option 1', 'Option 2', 'Option 3']}
|
|
164
|
+
placeholder="Select an option"
|
|
165
|
+
/>
|
|
166
|
+
);
|
|
167
|
+
}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### Disabled Select
|
|
171
|
+
|
|
172
|
+
```tsx
|
|
173
|
+
import * as React from 'react';
|
|
174
|
+
import { Select } from '@xsolla/xui-select';
|
|
175
|
+
|
|
176
|
+
export default function DisabledSelect() {
|
|
177
|
+
return (
|
|
178
|
+
<Select
|
|
179
|
+
label="Disabled Field"
|
|
180
|
+
value="Option 1"
|
|
181
|
+
state="disable"
|
|
182
|
+
options={['Option 1', 'Option 2', 'Option 3']}
|
|
183
|
+
/>
|
|
184
|
+
);
|
|
185
|
+
}
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### Unfilled/Transparent Background
|
|
189
|
+
|
|
190
|
+
```tsx
|
|
191
|
+
import * as React from 'react';
|
|
192
|
+
import { Select } from '@xsolla/xui-select';
|
|
193
|
+
|
|
194
|
+
export default function UnfilledSelect() {
|
|
195
|
+
return (
|
|
196
|
+
<Select
|
|
197
|
+
filled={false}
|
|
198
|
+
options={['Option 1', 'Option 2', 'Option 3']}
|
|
199
|
+
placeholder="Transparent background"
|
|
200
|
+
/>
|
|
201
|
+
);
|
|
202
|
+
}
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### Icon Only Select
|
|
206
|
+
|
|
207
|
+
```tsx
|
|
208
|
+
import * as React from 'react';
|
|
209
|
+
import { Select } from '@xsolla/xui-select';
|
|
210
|
+
import { Settings } from '@xsolla/xui-icons';
|
|
211
|
+
|
|
212
|
+
export default function IconOnlySelect() {
|
|
213
|
+
return (
|
|
214
|
+
<Select
|
|
215
|
+
iconOnly
|
|
216
|
+
iconLeft={<Settings />}
|
|
217
|
+
options={['Settings', 'Preferences', 'Advanced']}
|
|
218
|
+
/>
|
|
219
|
+
);
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
### Form with Select
|
|
224
|
+
|
|
225
|
+
```tsx
|
|
226
|
+
import * as React from 'react';
|
|
227
|
+
import { Select } from '@xsolla/xui-select';
|
|
228
|
+
import { Input } from '@xsolla/xui-input';
|
|
229
|
+
import { Button } from '@xsolla/xui-button';
|
|
230
|
+
|
|
231
|
+
export default function FormWithSelect() {
|
|
232
|
+
const [form, setForm] = React.useState({
|
|
233
|
+
name: '',
|
|
234
|
+
category: '',
|
|
235
|
+
priority: '',
|
|
236
|
+
});
|
|
237
|
+
|
|
238
|
+
return (
|
|
239
|
+
<div style={{ display: 'flex', flexDirection: 'column', gap: 16, width: 300 }}>
|
|
240
|
+
<Input
|
|
241
|
+
label="Task Name"
|
|
242
|
+
value={form.name}
|
|
243
|
+
onChangeText={(name) => setForm(prev => ({ ...prev, name }))}
|
|
244
|
+
placeholder="Enter task name"
|
|
245
|
+
/>
|
|
246
|
+
<Select
|
|
247
|
+
label="Category"
|
|
248
|
+
value={form.category}
|
|
249
|
+
onChange={(category) => setForm(prev => ({ ...prev, category }))}
|
|
250
|
+
options={['Development', 'Design', 'Marketing', 'Sales']}
|
|
251
|
+
placeholder="Select category"
|
|
252
|
+
/>
|
|
253
|
+
<Select
|
|
254
|
+
label="Priority"
|
|
255
|
+
value={form.priority}
|
|
256
|
+
onChange={(priority) => setForm(prev => ({ ...prev, priority }))}
|
|
257
|
+
options={[
|
|
258
|
+
{ label: 'High', value: 'high' },
|
|
259
|
+
{ label: 'Medium', value: 'medium' },
|
|
260
|
+
{ label: 'Low', value: 'low' },
|
|
261
|
+
]}
|
|
262
|
+
placeholder="Select priority"
|
|
263
|
+
/>
|
|
264
|
+
<Button>Create Task</Button>
|
|
265
|
+
</div>
|
|
266
|
+
);
|
|
267
|
+
}
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
## API Reference
|
|
25
271
|
|
|
26
272
|
### Select
|
|
27
273
|
|
|
274
|
+
The main select component. Renders a button trigger with dropdown menu.
|
|
275
|
+
|
|
276
|
+
**Select Props:**
|
|
277
|
+
|
|
28
278
|
| Prop | Type | Default | Description |
|
|
29
|
-
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
|
33
|
-
|
|
|
34
|
-
| `
|
|
35
|
-
|
|
|
36
|
-
| `
|
|
37
|
-
|
|
|
38
|
-
|
|
|
39
|
-
|
|
|
279
|
+
| :--- | :--- | :------ | :---------- |
|
|
280
|
+
| value | `string` | - | The controlled selected value. |
|
|
281
|
+
| placeholder | `string` | `"Select"` | Placeholder text when no value selected. |
|
|
282
|
+
| onPress | `() => void` | - | Callback when select trigger is pressed. |
|
|
283
|
+
| size | `"xl" \| "lg" \| "md" \| "sm" \| "xs"` | `"md"` | The size of the select. |
|
|
284
|
+
| state | `"default" \| "hover" \| "focus" \| "disable" \| "error"` | `"default"` | The visual state of the select. |
|
|
285
|
+
| label | `string` | - | Label text displayed above the select. |
|
|
286
|
+
| disabled | `boolean` | `false` | Whether the select is disabled. Also triggered when `state="disable"`. |
|
|
287
|
+
| errorMessage | `string` | - | Error message displayed below the select (also sets error styling). |
|
|
288
|
+
| iconLeft | `ReactNode` | - | Icon displayed on the left side. |
|
|
289
|
+
| iconRight | `ReactNode` | `<ChevronDown />` | Icon displayed on the right side. |
|
|
290
|
+
| filled | `boolean` | `true` | Whether to show filled background. |
|
|
291
|
+
| iconOnly | `boolean` | `false` | Whether to show only icon without text. |
|
|
292
|
+
| options | `(string \| SelectOption)[]` | `[]` | Array of options to display. |
|
|
293
|
+
| onChange | `(value: string) => void` | - | Callback when value changes. |
|
|
294
|
+
| searchable | `boolean` | `false` | Whether to show a search input in the dropdown. |
|
|
295
|
+
| searchPlaceholder | `string` | `"Search"` | Placeholder text for the search input. |
|
|
296
|
+
| noOptionsMessage | `string` | `"No results"` | Message shown when no options match the search. |
|
|
297
|
+
| maxHeight | `number` | `300` | Maximum height of the dropdown in pixels. |
|
|
298
|
+
|
|
299
|
+
**SelectOption Type:**
|
|
300
|
+
|
|
301
|
+
```typescript
|
|
302
|
+
interface SelectOption {
|
|
303
|
+
label: string; // Display text
|
|
304
|
+
value: any; // Value to be selected
|
|
305
|
+
disabled?: boolean; // Whether this option is disabled
|
|
306
|
+
}
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
## Theming
|
|
310
|
+
|
|
311
|
+
Select components use the design system theme for colors and sizing:
|
|
312
|
+
|
|
313
|
+
```typescript
|
|
314
|
+
// Colors accessed via theme
|
|
315
|
+
theme.colors.control.input.bg // Background color
|
|
316
|
+
theme.colors.control.input.bgHover // Hover background
|
|
317
|
+
theme.colors.control.input.bgFocus // Focus background
|
|
318
|
+
theme.colors.control.input.bgDisable // Disabled background
|
|
319
|
+
theme.colors.control.input.border // Border color
|
|
320
|
+
theme.colors.control.input.borderFocus // Focus border color
|
|
321
|
+
theme.colors.control.input.borderError // Error border color
|
|
322
|
+
theme.colors.control.input.text // Text color
|
|
323
|
+
theme.colors.control.brand.primary.bg // Selected option background
|
|
324
|
+
|
|
325
|
+
// Sizing accessed via theme
|
|
326
|
+
theme.sizing.input(size).height
|
|
327
|
+
theme.sizing.input(size).paddingVertical
|
|
328
|
+
theme.sizing.input(size).paddingHorizontal
|
|
329
|
+
theme.sizing.input(size).fontSize
|
|
330
|
+
|
|
331
|
+
// Border radius
|
|
332
|
+
theme.radius.button
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
**Dropdown Styling:**
|
|
336
|
+
|
|
337
|
+
| Property | Value |
|
|
338
|
+
| :------- | :---- |
|
|
339
|
+
| Max Height | 300px (configurable via `maxHeight` prop) |
|
|
340
|
+
| Box Shadow | 0 4px 12px rgba(0,0,0,0.1) |
|
|
341
|
+
| Z-Index | 1000 |
|
|
342
|
+
| Scroll | overflowY: auto |
|
|
343
|
+
|
|
344
|
+
## Accessibility
|
|
345
|
+
|
|
346
|
+
- Uses semantic button element for trigger
|
|
347
|
+
- Dropdown menu has proper focus management
|
|
348
|
+
- Keyboard navigation supported (Tab, Enter, Space, Escape)
|
|
349
|
+
- Selected item is visually highlighted
|
|
350
|
+
- Auto-scrolls to selected item when opened
|
|
351
|
+
- Focus indicators follow WCAG guidelines
|
|
352
|
+
- Disabled state properly communicated to assistive technology
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xsolla/xui-select",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.100.0",
|
|
4
4
|
"main": "./web/index.js",
|
|
5
5
|
"module": "./web/index.mjs",
|
|
6
6
|
"types": "./web/index.d.ts",
|
|
@@ -10,8 +10,8 @@
|
|
|
10
10
|
"build:native": "PLATFORM=native tsup"
|
|
11
11
|
},
|
|
12
12
|
"dependencies": {
|
|
13
|
-
"@xsolla/xui-core": "0.
|
|
14
|
-
"@xsolla/xui-primitives-core": "0.
|
|
13
|
+
"@xsolla/xui-core": "0.100.0",
|
|
14
|
+
"@xsolla/xui-primitives-core": "0.100.0"
|
|
15
15
|
},
|
|
16
16
|
"peerDependencies": {
|
|
17
17
|
"react": ">=16.8.0",
|