@primer/react/dist/FilteredActionList/FilteredActionList.d.ts

An implementation of GitHub's Primer Design System using React

import { ActionListProps } from "../ActionList/shared.js";
import { TextInputProps } from "../TextInput/TextInput.js";
import { FilteredActionListLoadingType } from "./constants.js";
import { GroupedListProps, ListPropsBase } from "./types.js";
import React, { JSX } from "react";

//#region src/FilteredActionList/FilteredActionList.d.ts
interface FilteredActionListProps extends Partial<Omit<GroupedListProps, keyof ListPropsBase>>, ListPropsBase {
  loading?: boolean;
  loadingType?: FilteredActionListLoadingType;
  placeholderText?: string;
  filterValue?: string;
  onFilterChange: (value: string, e: React.ChangeEvent<HTMLInputElement> | null) => void;
  onListContainerRefChanged?: (ref: HTMLElement | null) => void;
  onInputRefChanged?: (ref: React.RefObject<HTMLInputElement | null>) => void;
  /**
   * A ref assigned to the scrollable container wrapping the ActionList
   */
  scrollContainerRef?: React.Ref<HTMLDivElement | null>;
  textInputProps?: Partial<Omit<TextInputProps, 'onChange'>>;
  inputRef?: React.RefObject<HTMLInputElement | null>;
  message?: React.ReactNode;
  messageText?: {
    title: string;
    description: string;
  };
  className?: string;
  announcementsEnabled?: boolean;
  fullScreenOnNarrow?: boolean;
  onSelectAllChange?: (checked: boolean) => void;
  /**
   * Additional props to pass to the underlying ActionList component.
   */
  actionListProps?: Partial<ActionListProps>;
  /**
   * Determines how keyboard focus behaves when navigating beyond the first or last item in the list.
   *
   * - `'stop'`: Focus will stop at the first or last item; further navigation in that direction will not move focus.
   * - `'wrap'`: Focus will wrap around to the opposite end of the list when navigating past the boundaries (e.g., pressing Down on the last item moves focus to the first).
   *
   *  @default 'wrap'
   */
  focusOutBehavior?: 'stop' | 'wrap';
  /**
   * Callback function that is called when the active descendant changes.
   *
   * @param newActiveDescendant - The new active descendant element.
   * @param previousActiveDescendant - The previous active descendant element.
   * @param directlyActivated - Whether the active descendant was directly activated (e.g., by a keyboard event).
   */
  onActiveDescendantChanged?: (newActiveDescendant: HTMLElement | undefined, previousActiveDescendant: HTMLElement | undefined, directlyActivated: boolean) => void;
  /**
   * Private API for use internally only. Adds the ability to switch between
   * `active-descendant` and roving tabindex.
   *
   * By default, FilteredActionList uses `aria-activedescendant` to manage focus.
   *
   * Roving tabindex is an alternative focus management method that moves
   * focus to the list items themselves instead of keeping focus on the input.
   *
   * Improper usage can lead to inaccessible experiences, so this prop should be used with caution.
   *
   * For usage, refer to the documentation:
   *
   * WAI-ARIA `aria-activedescendant`: https://www.w3.org/TR/wai-aria-1.2/#aria-activedescendant
   *
   * Roving Tabindex: https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex
   *
   * @default 'active-descendant'
   */
  _PrivateFocusManagement?: 'roving-tabindex' | 'active-descendant';
  /**
   * If true, disables selecting items when hovering over them with the mouse.
   */
  disableSelectOnHover?: boolean;
  /**
   * If true, focus remains where it was and the user must interact to move focus.
   * If false, sets initial focus to the first item in the list when rendered, enabling keyboard navigation immediately.
   */
  setInitialFocus?: boolean;
  /**
   * Set to true to allow focus to move to elements that are dynamically prepended to the container.
   * Default is false.
   */
  focusPrependedElements?: boolean;
  /**
   * Determines the scroll behavior of the container when an item is focused.
   *
   * @default 'auto'
   */
  scrollBehavior?: ScrollBehavior;
  /**
   * If true, enables client-side list virtualization. Only the visible items (plus a small
   * overscan buffer) are rendered in the DOM, dramatically improving performance for large lists.
   *
   * This is a purely client-side optimization — it does not require server-side pagination.
   * The consumer can still pass all items at once; the component will only render what is visible.
   *
   * Recommended for lists with more than 100 items.
   *
   * Note: Has no effect when `groupMetadata` is provided, as grouped lists are
   * typically small enough not to need virtualization.
   *
   * @default false
   */
  virtualized?: boolean;
}
declare function FilteredActionList({
  loading,
  placeholderText,
  filterValue: externalFilterValue,
  loadingType,
  onFilterChange,
  onListContainerRefChanged,
  onInputRefChanged,
  items,
  textInputProps,
  inputRef: providedInputRef,
  scrollContainerRef: providedScrollContainerRef,
  groupMetadata,
  showItemDividers,
  message,
  messageText,
  className,
  selectionVariant,
  announcementsEnabled,
  fullScreenOnNarrow,
  onSelectAllChange,
  actionListProps,
  focusOutBehavior,
  _PrivateFocusManagement,
  onActiveDescendantChanged,
  disableSelectOnHover,
  setInitialFocus,
  focusPrependedElements,
  scrollBehavior,
  virtualized,
  ...listProps
}: FilteredActionListProps): JSX.Element;
declare namespace FilteredActionList {
  var displayName: string;
}
//#endregion
export { FilteredActionList, FilteredActionListProps };