Select With Query
Select With Query - это мощный компонент выпадающего списка, основанный на Autocomplete из HeroUI, с встроенной поддержкой асинхронной загрузки данных через React Query. Компонент предоставляет удобный API для работы с серверными данными, серверным поиском и легко интегрируется с React Hook Form.
Import
Usage
Базовый пример использования с простой загрузкой данных.
Важно: Компонент требует обертки в QueryClientProvider из @tanstack/react-query.
Основные возможности
С начальным значением
Вы можете задать начальное значение используя свойство value.
Серверный поиск
Включите серверный поиск с помощью enableSearch. Компонент автоматически добавит параметры поиска в запрос.
Интеграция с React Hook Form
Полная интеграция с React Hook Form для удобной работы с формами и валидацией.
Зависимые селекты
Легко реализуйте зависимые селекты, используя параметры запроса и условную загрузку данных.
Кастомный рендеринг
Настройте отображение опций и выбранного значения с помощью renderOption и renderValue.
С описанием
Добавьте описание для лучшего UX.
Валидация и состояния
С валидацией
Используйте валидацию совместно со свойствами isInvalid и errorMessage.
Disabled
Отключенное состояние блокирует взаимодействие с компонентом.
Стилизация
Sizes
Select With Query поддерживает три размера: sm, md (по умолчанию) и lg.
Variants
Select With Query поддерживает все варианты стилей из HeroUI Autocomplete.
Colors
Select With Query поддерживает различные цветовые темы.
React Query конфигурация
Query Options
Свойство queryOptions принимает объект или функцию, которая возвращает объект опций для useQuery из React Query.
Transform Data
Используйте transformData для преобразования данных из API в формат опций.
Серверный поиск
Для включения серверного поиска:
Свойства
SelectWithQuery Props
| Атрибут | Тип | Описание | По умолчанию |
|---|---|---|---|
| queryOptions | UseQueryOptions | ((params) => UseQueryOptions) | Опции для React Query (обязательное) | - |
| transformData | (data: TData) => TTransformed[] | Функция трансформации данных | - |
| labelKey | string | Ключ для label при дефолтной трансформации | "label" |
| valueKey | string | Ключ для value при дефолтной трансформации | "value" |
| enableSearch | boolean | Включить серверный поиск | false |
| searchParamName | string | Имя параметра поиска | "search" |
| searchDebounce | number | Задержка дебаунса поиска (мс) | 300 |
| minSearchLength | number | Минимальная длина запроса для поиска | 0 |
| value | string | number | null | Текущее выбранное значение | - |
| defaultValue | string | number | null | Значение по умолчанию | - |
| onSelectionChange | (value: string | number | null) => void | Callback при изменении | - |
| getOptionValue | (item: TTransformed) => string | number | Функция получения значения опции | (item) => item.value |
| getOptionLabel | (item: TTransformed) => string | Функция получения label опции | (item) => item.label |
| renderOption | (item: TTransformed) => ReactNode | Кастомный рендер опции | - |
| renderValue | (item: TTransformed | null) => ReactNode | Кастомный рендер выбранного значения | - |
| emptyContent | ReactNode | Контент при пустом списке | "Нет доступных опций" |
| loadingContent | ReactNode | Контент при загрузке | "Загрузка..." |
| errorContent | ReactNode | ((error: TError) => ReactNode) | Контент при ошибке | - |
| onCreateItem | () => void | Callback для создания нового элемента | - |
| onSearchChange | (value: string) => void | Callback при изменении поиска | - |
Наследуемые свойства Autocomplete
Select With Query наследует все свойства от HeroUI Autocomplete компонента:
- label: Label для поля
- placeholder: Placeholder текст
- description: Описание под полем
- errorMessage: Сообщение об ошибке
- isInvalid: Флаг невалидного состояния
- isDisabled: Флаг отключенного состояния
- isReadOnly: Флаг только для чтения
- isRequired: Флаг обязательного поля
- labelPlacement: Позиция label (
inside,outside,outside-left) - size: Размер компонента (
sm,md,lg) - color: Цвет темы (
default,primary,secondary,success,warning,danger) - variant: Вариант стиля (
flat,bordered,faded,underlined) - radius: Радиус скругления
- startContent: Контент слева от поля
- endContent: Контент справа от поля
- И другие свойства из Autocomplete API
Типизация
Select With Query поддерживает generic типы для типобезопасности:
Примеры использования
Работа с API
Зависимые запросы
Best Practices
- Query Keys: Используйте уникальные и описательные ключи запросов
- Transform Data: Всегда трансформируйте данные в единый формат для упрощения работы
- Error Handling: Обрабатывайте ошибки загрузки через
errorContent - Search Debounce: Используйте дебаунс для серверного поиска (300-500ms)
- Dependent Selects: Используйте
enabledопцию вqueryOptionsдля зависимых селектов - TypeScript: Используйте generic типы для типобезопасности
Зависимости
@heroui/react- для базового Autocomplete компонента@tanstack/react-query- для управления асинхронными даннымиreact-hook-form(опционально) - для интеграции с формами
