> ## Documentation Index
> Fetch the complete documentation index at: https://sonamu.cartanova.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# ID Async Select
> Async select component for selecting relational data
Learn how to use the ID Async Select component for handling foreign key relationships.
## ID Async Select Overview
API calls
Autocomplete
Entity based
ID type guaranteed
Real-time filtering
Debounce
Single/Multiple modes
Array return
## What is ID Async Select?
### Problem: Complexity of Foreign Key Selection
When handling foreign key relationships in databases, the frontend needs to **select related entities**.
**Problems with traditional approach**:
```typescript theme={null}
// ❌ Load all users at once (inefficient)
const [users, setUsers] = useState([]);
useEffect(() => {
userService.list({ pageSize: 1000 }).then(({ users }) => {
setUsers(users); // Load all 1000 users!
});
}, []);
return (
);
```
**Problems**:
1. **Performance**: Loading time increases with more data
2. **Memory**: All unnecessary data loaded into memory
3. **UX**: Hard for users to find desired items
4. **Scalability**: Can't handle continuous data growth
### Solution: ID Async Select
Sonamu's ID Async Select **loads asynchronously only when needed** and provides **search functionality**.
```typescript theme={null}
// ✅ Load only needed data based on search terms
import { IdAsyncSelect } from "@sonamu-kit/react-components";
import { UserAsyncIdConfig } from "@/services/services.generated";
```
**Benefits**:
1. ✨ **Performance**: Load minimum initially, only what's needed on search
2. ✨ **User experience**: Quick selection with autocomplete
3. ✨ **Type safe**: Entity type automatically applied
4. ✨ **Scalability**: No problem regardless of data volume
## Basic Usage
### Required Props
ID Async Select uses these two core props:
* `config`: AsyncIdConfig object auto-generated from `services.generated.ts`
* `subset`: Subset key to query (e.g., "A", "D", etc.)
```typescript theme={null}
import { IdAsyncSelect } from "@sonamu-kit/react-components";
import { UserAsyncIdConfig } from "@/services/services.generated";
```
### Single Selection
Select one entity.
```typescript theme={null}
import { IdAsyncSelect } from "@sonamu-kit/react-components";
import { UserAsyncIdConfig } from "@/services/services.generated";
import { useState } from "react";
function PostForm() {
const [authorId, setAuthorId] = useState(null);
return (
);
}
```
**How it works**:
1. Call search API when user types
2. Display search results in dropdown
3. Only save ID when selected (memory efficient)
### Multiple Selection
Select multiple entities.
```typescript theme={null}
import { TagAsyncIdConfig } from "@/services/services.generated";
function PostForm() {
const [tagIds, setTagIds] = useState([]);
return (
);
}
```
**Multiple selection features**:
* Display selected items as tags
* Remove individually with X button
* Return IDs as array (`number[]`)
### Setting Initial Values
Set initial values when editing existing data.
```typescript theme={null}
function EditPostForm({ post }: { post: Post }) {
const [authorId, setAuthorId] = useState(post.author_id);
return (
);
}
```
**Initial value handling**:
* Passing ID to `value` automatically loads the entity
* Background single query for label display
* Display only ID while loading
## displayField Options
### Specify by Field Name
The simplest way - specify the field name as a string.
```typescript theme={null}
```
### Specify by Callback Function
Use a callback function when complex labels are needed.
```typescript theme={null}
`${row.employee_number} (Department: ${row.department?.name})`
}
/>
```
### Auto Detection (Omit displayField)
When `displayField` is omitted, an appropriate field is automatically detected.
```typescript theme={null}
// Auto detection applied when displayField is omitted
```
**Detection priority**:
1. name-like fields: `name`, `title`, `label`, `display_name`, `username`
2. First string type column (excluding id)
3. fallback: `id`
## Advanced Usage
### Pass Search Conditions with baseListParams
Set default search parameters.
```typescript theme={null}
```
### Get Full Row Data with onRowChange
When you need the full selected Row data, not just the ID:
```typescript theme={null}
function SelectWithRowData() {
const [userId, setUserId] = useState(null);
const [selectedUser, setSelectedUser] = useState();
return (
setSelectedUser(row as User)}
displayField="username"
/>
);
}
```
### Change valueField
By default, the `id` field is used as the value, but you can use a different field.
```typescript theme={null}
```
## Type Safety
### AsyncIdConfig Structure
The Config auto-generated from `services.generated.ts` has this structure:
```typescript theme={null}
// Auto-generated in services.generated.ts
export const UserAsyncIdConfig: AsyncIdConfig<
"A" | "D", // TSubsetKey - Available Subset keys
UserSubsetMapping, // TSubsetMapping - Subset type mapping
UserListParams // TListParams - Search parameter types
> = {
placeholderKey: "user.placeholder",
useList: UserService.useList,
};
```
### Utilizing Type Inference
Types are automatically inferred through Config:
```typescript theme={null}
{
// row type is inferred as UserSubsetA
console.log(row.username);
}}
/>
```
## Practical Examples
### Post Creation Form
```typescript theme={null}
import { useState } from "react";
import { IdAsyncSelect } from "@sonamu-kit/react-components";
import {
UserAsyncIdConfig,
CategoryAsyncIdConfig,
TagAsyncIdConfig
} from "@/services/services.generated";
import { postService } from "@/services/post.service";
function CreatePostForm() {
const [title, setTitle] = useState("");
const [content, setContent] = useState("");
const [authorId, setAuthorId] = useState(null);
const [categoryId, setCategoryId] = useState(null);
const [tagIds, setTagIds] = useState([]);
async function handleSubmit() {
if (!authorId || !categoryId) {
alert("Please select author and category");
return;
}
await postService.create({
title,
content,
author_id: authorId,
category_id: categoryId,
tag_ids: tagIds,
});
}
return (