الإكمال التلقائي واجهة البرمجة

الفتحات

في Autocomplete عدد 22 من الفتحات. مرّر بديلًا لأي منها في components، وكل فتحة لا تمرّرها تبقى على بديلها الافتراضي. فتحات العناصر تستقبل خصائص DOM فيناسبها عنصر المكتبة كما هو، وفتحات الأدوات تستقبل خصائص مسمّاة وتحتاج عادة إلى بضعة أسطر من المحوّل.

الاسم	النوع	الخصائص التي تستقبلها	البديل الافتراضي	سمات `data-*`
`Root`	<element>	خصائص DOM: `Omit<HTMLAttributes<HTMLDivElement>, "color">` `ref?: Ref<HTMLDivElement>`	مصدر البديل `Root: ({ className, ...props }) => <div className={cx("sac", className)} {...props} />`	`data-disabled` `data-empty` `data-invalid` `data-open`
`Trigger`	<element>	خصائص DOM: `Omit<HTMLAttributes<HTMLDivElement>, "color">` `ref?: Ref<HTMLDivElement>`	مصدر البديل `Trigger: ({ className, ...props }) => <div className={cx("sac__trigger", className)} {...props} />`	`data-disabled` `data-empty` `data-invalid` `data-open` `data-search-in`
`TriggerInput`	<element>	خصائص DOM: `Omit<InputHTMLAttributes<HTMLInputElement>, "color" \| "size">` `ref?: Ref<HTMLInputElement>`	مصدر البديل `TriggerInput: ({ className, ...props }) => <input className={cx("sac__trigger-input", className)} {...props} />`	—
`Toggle`	<element>	خصائص DOM: `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "color">` `ref?: Ref<HTMLButtonElement>`	مصدر البديل `Toggle: ({ className, ...props }) => <button className={cx("sac__toggle", className)} {...props} />`	`data-open`
`Value`	{widget}	`label?: string` The selected option's text, when there is one. `placeholder: string` Shown when nothing is selected. `empty: boolean` Whether anything is selected.	مصدر البديل `Value: ({ label, placeholder, empty }) => ( <span className={cx("sac__value", empty && "sac__value--empty")}>{empty ? placeholder : label}</span> )`	—
`Tag`	{widget}	`label: string` The option's text, falling back to its id when the option is unknown. `value: OptionValue` The id this tag stands for. `option?: TOption` The option behind it, when it is known. `onRemove: () => void` Removes just this value. `removeLabel: string` Accessible name for the remove control. `disabled: boolean` Whether the control is disabled.	مصدر البديل `Tag: ({ label, onRemove, removeLabel, disabled }) => ( <span className="sac__tag"> <span className="sac__tag-label">{label}</span> {!disabled && ( <button type="button" className="sac__tag-remove" aria-label={removeLabel} onClick={(event) => { event.stopPropagation(); onRemove(); }} > <CrossIcon /> </button> )} </span> )`	—
`Clear`	{widget}	`onClick: () => void` Clears the selection. `aria-label: string` Accessible name.	مصدر البديل `Clear: ({ onClick, ...aria }) => ( <button type="button" className="sac__clear" onClick={(event) => { event.stopPropagation(); onClick(); }} {...aria} > <CrossIcon /> </button> )`	—
`Indicator`	{widget}	`open: boolean` Whether the popup is open. `loading: boolean` Whether a first page is in flight.	مصدر البديل `Indicator: ({ loading }) => loading ? <span className="sac__spinner" aria-hidden="true" /> : <ChevronIcon />`	—
`Popup`	<element>	خصائص DOM: `Omit<HTMLAttributes<HTMLDivElement>, "color">` `ref?: Ref<HTMLDivElement>`	مصدر البديل `Popup: ({ className, ...props }) => <div className={cx("sac__popup", className)} {...props} />`	`data-placement`
`Search`	<element>	خصائص DOM: `Omit<InputHTMLAttributes<HTMLInputElement>, "color" \| "size">` `ref?: Ref<HTMLInputElement>`	مصدر البديل `Search: ({ className, ...props }) => <input className={cx("sac__search", className)} {...props} />`	—
`List`	<element>	خصائص DOM: `Omit<HTMLAttributes<HTMLUListElement>, "color">` `ref?: Ref<HTMLUListElement>`	مصدر البديل `List: ({ className, ...props }) => <ul className={cx("sac__list", className)} {...props} />`	—
`Option`	<element>	خصائص DOM: `Omit<LiHTMLAttributes<HTMLLIElement>, "color">` `ref?: Ref<HTMLLIElement>`	مصدر البديل `Option: ({ className, ...props }) => <li className={cx("sac__option", className)} {...props} />`	`data-disabled` `data-highlighted` `data-index` `data-selected`
`OptionLabel`	{widget}	`option: TOption` The whole option. `label: string` Its text, as `getOptionLabel` returned it. `selected: boolean` Whether it is selected. `highlighted: boolean` Whether it is the active option. `disabled: boolean` Whether it can be picked.	مصدر البديل `OptionLabel: ({ label }) => <span className="sac__label">{label}</span>`	—
`Check`	{widget}	`selected: boolean` Whether to render as selected.	مصدر البديل `Check: ({ selected }) => (selected ? <CheckIcon /> : null)`	—
`Group`	<element>	خصائص DOM: `Omit<HTMLAttributes<HTMLUListElement>, "color">` `label: string` The group's name, which is also its label. `labelId: string` The id of the label element the group is labelled by. `children?: ReactNode` The label row, then the group's option rows. `ref?: Ref<HTMLUListElement>`	مصدر البديل `Group: ({ label: _label, labelId: _labelId, className, ...props }) => ( <li className="sac__group" role="none"> <ul className={cx("sac__group-list", className)} {...props} /> </li> )`	—
`GroupLabel`	{widget}	`id: string` The id the group's `aria-labelledby` points at. `role: "presentation"` Keeps the row from being read as a list item. `label: string` The group's name. `hidden?: boolean` Set on the copy a windowed list keeps for a group whose label row has scrolled away. Pass it on to the element: the group stays named through it, and it takes no space.	مصدر البديل `GroupLabel: ({ label, ...props }) => ( <li className="sac__group-label" {...props}> {label} </li> )`	—
`Separator`	<element>	خصائص DOM: `Omit<LiHTMLAttributes<HTMLLIElement>, "color">` `ref?: Ref<HTMLLIElement>`	مصدر البديل `Separator: ({ className, ...props }) => <li className={cx("sac__separator", className)} {...props} />`	—
`Empty`	{widget}	`query: string` The current search text. `status: AutocompleteStatus` Why the list is empty. Either `empty` or `min-chars`. `message: string` The message for that reason.	مصدر البديل `Empty: ({ message }) => <li className="sac__message">{message}</li>`	—
`Loading`	{widget}	`message: string` The message.	مصدر البديل `Loading: ({ message }) => ( <li className="sac__message"> <span className="sac__spinner" aria-hidden="true" /> {message} </li> )`	—
`Error`	{widget}	`error: string` The message. `onRetry?: () => void` Retries, when the caller provided a way to. `retryLabel: string` Label for the retry control.	مصدر البديل `Error: ({ error, onRetry, retryLabel }) => ( <li className="sac__error"> <span>{error}</span> {onRetry ? ( <button type="button" className="sac__button" onClick={onRetry}> {retryLabel} </button> ) : null} </li> )`	—
`Create`	{widget}	`query: string` The text that would be created. `onCreate: () => void` Creates it. `loading: boolean` Whether the create request is in flight. `label: string` The rendered label, e.g. `Create "Acme"`.	مصدر البديل `Create: ({ onCreate, loading, label }) => ( <li className="sac__create"> <button type="button" className="sac__create-button" onClick={onCreate} disabled={loading}> <PlusIcon /> {label} </button> </li> )`	—
`LoadMore`	{widget}	`ref?: Ref<HTMLLIElement>` Attach to the element that should be observed. `onLoadMore: () => void` Requests the next page. `loading: boolean` Whether that page is already in flight. `label: string` The label for the current state.	مصدر البديل `LoadMore: ({ ref, onLoadMore, loading, label }) => ( <li ref={ref} className="sac__more"> <button type="button" className="sac__more-button" onClick={onLoadMore} disabled={loading}> {loading ? <span className="sac__spinner" aria-hidden="true" /> : null} {label} </button> </li> )`	—

الخصائص

كل خصائص Autocomplete مجمّعة كما في توثيق المكتبة. الحالة المتحكَّم بها تأتي أزواجًا: مرّر القيمة مع معالج تغييرها، أو القيمة الابتدائية وحدها لتبقى الحالة داخل المكوّن.

الاسم	النوع	الافتراضي	الوصف
Options
`options`مطلوبة	`TOption[]`	—	The options to render.
`getOptionValue`	`GetOptionValue<TOption>`	—	Reads an option's id. Default: `option.value ?? option.id`. Every option's value must be unique: it keys the rows and builds their DOM ids, so two options with one value would share an id.
`getOptionLabel`	`GetOptionLabel<TOption>`	—	Reads an option's text. Default: `option.label ?? option.name`.
`optionDisabled`	`(option: TOption) => boolean`	—	Marks an option unselectable. It stays visible but cannot be landed on.
`getOptionGroup`	`GetOptionGroup<TOption>`	—	Reads the group an option belongs to, which is also the group's label. The options stay one flat list: groups appear in the order their first option does, an option joins its group wherever it sits (a later page included), and the options with no group form one unlabelled section where the first of them appeared. A group the search empties disappears with its label and separator. Read whenever the options or the search change.
`filter`	`OptionFilter<TOption>`	—	How to narrow options against the search. `false` filters nothing.
`selected`single mode	`TOption \| null`	—	The option behind `value`, for an id whose option is not in `options`.
`selected`multiple mode	`TOption[]`	—	The options behind `value`, for ids whose options are not in `options`.
Selection
`multiple`single mode	`false`	—	One value at a time.
`multiple`مطلوبةmultiple mode	`true`	—	Several values, with the popup staying open on each pick.
`value`single mode	`OptionValue \| null`	—	The selected id, or `null` for nothing.
`value`multiple mode	`OptionValue[]`	—	The selected ids.
`defaultValue`single mode	`OptionValue \| null`	—	The selected id while uncontrolled.
`defaultValue`multiple mode	`OptionValue[]`	—	The selected ids while uncontrolled.
`onChange`single mode	`(value: OptionValue \| null, option?: TOption) => void`	—	The new id and, where known, the option behind it. `null` means cleared.
`onChange`multiple mode	`(values: OptionValue[], options: (TOption \| undefined)[]) => void`	—	The new ids, and the options index-aligned with them. An entry is `undefined` only when an id was supplied that no option has been seen for, so the two arrays always correspond.
`clearable`	`boolean`	—	Whether the clear control is offered. Default `true`.
`closeOnSelect`	`boolean`	`!multiple`	Whether picking closes the popup. Defaults to `!multiple`.
`name`	`string`	—	Renders a hidden input per value, so a plain HTML form submits it.
Search
`searchable`	`boolean`	—	Whether the search box renders. `false` makes it a select with typeahead.
`searchIn`	`"popup" \| "trigger"`	—	Where the search box sits. `"popup"` puts it at the top of the popup, behind a trigger that is a button. `"trigger"` makes the trigger an editable combobox: an input inside the field, which keeps focus the whole time, shows the picked label while closed in single mode, and sits after the tags in multiple mode. Ignored when `searchable` is `false`, which keeps the button trigger. Default `"popup"`.
`searchQuery`	`string`	—	The search text. With `searchIn="trigger"` the parent owns what the input shows while this is not empty, open or closed; the picked label returns once the parent sets it back to `""`, which a close asks for through `onSearchChange("")`.
`defaultSearchQuery`	`string`	—	The search text while uncontrolled.
`onSearchChange`	`(query: string) => void`	—	Told when the search text changes, for remote options.
`minChars`	`number`	—	Don't search until this many characters are typed.
Open state and keyboard
`open`	`boolean`	—	Whether the popup is open.
`defaultOpen`	`boolean`	—	Whether the popup starts open.
`onOpenChange`	`(open: boolean) => void`	—	Told when the popup opens or closes.
`loop`	`boolean`	—	Whether the highlight wraps past the ends. Default `false`.
`autoHighlight`	`boolean`	—	Highlight the first enabled option whenever the list opens or its contents change, so Enter picks the top match. A highlight the user moved themselves is kept until the search changes. Default `false`.
`disabled`	`boolean`	—	Nothing can be opened, picked or cleared.
`invalid`	`boolean`	—	The value failed validation. Sets `aria-invalid` on the combobox and `data-invalid` on the root and trigger, so a skin can show its error style. Pair it with `aria-errormessage` or `aria-describedby` pointing at the message. Default `false`.
`onBlur`	`(event: FocusEvent<HTMLElement>) => void`	—	Told when focus leaves the whole control, for form libraries.
Remote options
`loading`	`boolean`	—	A first page is in flight.
`error`	`string`	—	The last fetch failed. Replaces the list.
`onRetry`	`() => void`	—	Offers a way back from the error.
`hasMore`	`boolean`	—	Another page exists.
`onLoadMore`	`() => void`	—	Asks for the next page.
`loadingMore`	`boolean`	—	That next page is in flight.
Creating
`creatable`	`boolean`	—	Offers a "create <query>" row when the search matches nothing.
`onCreate`	`(query: string) => void`	—	Creates the searched name.
`createLoading`	`boolean`	—	The create request is in flight.
Rendering
`components`	`Partial<AutocompleteComponents<TOption>>`	—	Replace any part; the rest fall back to `SlotsmithProvider`'s `components.autocomplete`, then to the built-in ones.
`labels`	`Partial<AutocompleteLabels>`	—	Override any string. Wins over `locale`.
`locale`	`LocaleInput`	the provider's	The language: a locale object, or the tag of one given to `SlotsmithProvider`. Defaults to the provider's.
`slotProps`	`AutocompleteSlotProps`	—	Extra DOM props for the element parts.
`placeholder`	`string`	`labels.placeholder`	Trigger text when nothing is selected. Defaults to `labels.placeholder`.
`maxTags`	`number`	`2`	Tags shown before the rest collapse into `+N`. Defaults to 2.
`virtual`	`AutocompleteVirtualOptions`	—	Renders only the options in view, for lists of thousands: pass the virtualizer hook (`useVirtualizer` from `@tanstack/react-virtual`) as `use`, and the sizes.
Positioning
`placement`	`PopupPlacement`	`bottom`	Which side of the trigger the popup prefers. Defaults to `bottom`.
`popupOffset`	`number`	`4`	Gap between trigger and popup, in pixels. Defaults to 4.
`matchTriggerWidth`	`boolean`	`true`	Make the popup exactly as wide as the trigger. Defaults to `true`.
`popupMaxHeight`	`number`	`320`	Upper bound on the popup's height, in pixels. Defaults to 320.
`portal`	`PortalTarget`	`false`	Renders the popup in a portal: `true` for `document.body`, or an element of your own. It then escapes any ancestor's `overflow`, `transform` or stacking context, and still counts as part of the control. Set the `--ss-*` tokens and the dark class on `:root` or on that element, which the popup then inherits from. Defaults to `false`.

تُمرَّر أي خاصية أخرى إلى العنصر الجذر <div>.

النصوص واللغات

كل نص يعرضه Autocomplete أو يعلنه، مع قيمته الافتراضية بالإنجليزية. مرّر labels لتغيير بعضها في مكوّن واحد، أو locale لتحويل كل النصوص إلى لغة أخرى. العرض أدناه يفعل الأمرين.

المفتاح	النوع	الافتراضي بالإنجليزية	الوصف
`placeholder`	`string`	`"Select…"`	Trigger text when nothing is selected.
`search`	`string`	`"Search…"`	Placeholder for the search box.
`clear`	`string`	`"Clear selection"`	Accessible name for the clear control.
`toggle`	`string`	`"Show options"`	Accessible name for the button that opens and closes the list, with `searchIn="trigger"`.
`remove`	`(label: string) => string`	`remove("Lisbon")` يطبع `"Remove Lisbon"`	Accessible name for a tag's remove control.
`empty`	`string`	`"No results"`	Shown when a search returned nothing.
`loading`	`string`	`"Loading…"`	Shown while a first page is loading.
`minChars`	`(count: number) => string`	`minChars(3)` يطبع `"Type 3 or more characters to search"`	Shown before `minChars` characters have been typed.
`retry`	`string`	`"Retry"`	Label for the retry control.
`create`	`(query: string) => string`	`create("Lis")` يطبع `"Create “Lis”"`	Label for the create row.
`creating`	`string`	`"Creating…"`	Label for the create row while the request is in flight.
`more`	`(count: number) => string`	`more(3)` يطبع `"+3"`	The overflow badge in multiple mode.
`loadMore`	`string`	`"Load more"`	Label for the load-more control.
`results`	`(count: number) => string`	`results(3)` يطبع `"3 results"`	Announced to screen readers when the result count changes.

import { Autocomplete } from "slotsmith/autocomplete";
import { de } from "slotsmith/locales/de";

const cities = [
  { value: "berlin", label: "Berlin" },
  { value: "hamburg", label: "Hamburg" },
  { value: "koeln", label: "Köln" },
  { value: "leipzig", label: "Leipzig" },
  { value: "muenchen", label: "München" },
];

export default function Labels() {
  return (
    <Autocomplete
      options={cities}
      // Every string in German, from the ready-made pack…
      locale={de}
      // …except these two, replaced for this picker only.
      labels={{ placeholder: "Stadt wählen…", empty: "Keine Stadt gefunden" }}
      aria-label="Stadt"
      style={{ maxWidth: 320 }}
    />
  );
}

حزم اللغات الجاهزة ودعم الكتابة من اليمين إلى اليسار واللغة على مستوى التطبيق موضّحة في صفحة اللغات.

التنسيق

أسماء الأصناف التي تضعها البدائل الافتراضية في Autocomplete على عناصرها، والمتغيرات التي يقرؤها ملف تنسيقه. اضبط متغيرًا على المكوّن أو على أي عنصر يحيط به لتغيير مظهره، واستهدف الصنف فقط لما لا يغطيه متغير.

الصنف	الفتحة
`.sac`	`Root`
`.sac__body`	—
`.sac__overflow`	—
`.sac__sr-only`	—
`.sac__chevron`	`Indicator`
`.sac__tick`	`Check`
`.sac__cross`	—
`.sac__plus`	—
`.sac__tag`	`Tag`
`.sac__tag-label`	—
`.sac__tag-remove`	—
`.sac__clear`	`Clear`
`.sac__spinner`	—
`.sac__label`	`OptionLabel`
`.sac__message`	`Empty` `Loading`
`.sac__error`	`Error`
`.sac__button`	—
`.sac__create`	`Create`
`.sac__create-button`	—
`.sac__more`	`LoadMore`
`.sac__more-button`	—
`.sac__trigger`	`Trigger`
`.sac__trigger-input`	`TriggerInput`
`.sac__toggle`	`Toggle`
`.sac__value`	`Value`
`.sac__value--empty`	—
`.sac__popup`	`Popup`
`.sac__search`	`Search`
`.sac__list`	`List`
`.sac__option`	`Option`
`.sac__group`	`Group`
`.sac__group-list`	—
`.sac__group-label`	`GroupLabel`
`.sac__separator`	`Separator`

المتغير	الطبقة
`--sac-accent`	هذا المكوّن
`--sac-border`	هذا المكوّن
`--sac-danger`	هذا المكوّن
`--sac-font-size`	هذا المكوّن
`--sac-hover`	هذا المكوّن
`--sac-muted`	هذا المكوّن
`--sac-radius`	هذا المكوّن
`--sac-surface`	هذا المكوّن
`--sac-text`	هذا المكوّن
`--ss-accent`	مشترك بين كل المكوّنات
`--ss-border`	مشترك بين كل المكوّنات
`--ss-danger`	مشترك بين كل المكوّنات
`--ss-font-size`	مشترك بين كل المكوّنات
`--ss-hover`	مشترك بين كل المكوّنات
`--ss-muted`	مشترك بين كل المكوّنات
`--ss-radius`	مشترك بين كل المكوّنات
`--ss-surface`	مشترك بين كل المكوّنات
`--ss-text`	مشترك بين كل المكوّنات

تنتقل كل المتغيرات إلى قيمها الداكنة تحت .dark, [data-theme="dark"]، على الصفحة أو على أي عنصر يحيط بالمكوّن.

صفحة السمات تشرح المتغيرات والسمات الجاهزة.