Tree

API

Generated CoreAI prop summaries, not replacement type declarations. Most native DOM/event and ARIA props are omitted. ? means optional; JSDoc shows defaults, deprecations, and conditional requirements. Defaults assume the standard CoreAI provider.

Tree API

The Tree component renders nested items in a hierarchical structure. Use it with TreeItem component and layouts components TreeItemLayout or TreeItemPersonaLayout.

interface TreeProps {
  /**
   * A tree item can have various appearances:
   * - 'subtle' (default): The default tree item styles.
   * - 'subtle-alpha': Minimizes emphasis on hovered or focused states.
   * - 'transparent': Removes background color.
   * @default 'subtle'
   */
  appearance?: "subtle" | "transparent" | "subtle-alpha";

  as?: "div";

  /**
   * This refers to a list of ids of checked tree items, or a list of tuples of ids and checked state.
   * Controls the state of the checked tree items.
   * These property is ignored for subtrees.
   */
  checkedItems?: Iterable<TreeItemValue | [TreeItemValue, TreeSelectionValue]>;

  children?: any;

  className?: string;

  collapseMotion?: PresenceMotionSlotProps<CollapseParams> | null;

  /**
   * This refers to a list of ids of default opened items.
   * This property is ignored for subtrees.
   */
  defaultOpenItems?: Iterable<TreeItemValue>;

  /**
   * Indicates how navigation between a treeitem and its actions work
   * - 'tree' (default): The default navigation, pressing right arrow key navigates inward the first inner children of a branch treeitem
   * - 'treegrid': Pressing right arrow key navigate towards the actions of a treeitem
   * @default 'tree'
   */
  navigationMode?: "tree" | "treegrid";

  /**
   * Callback fired when the component changes value from checked state.
   * These property is ignored for subtrees.
   */
  onCheckedChange?: ((event: ChangeEvent<HTMLElement>, data: TreeCheckedChangeData) => void);

  /**
   * Callback fired when navigation happens inside the component.
   * These property is ignored for subtrees.
   *
   * FIXME: This method is not ideal, as navigation should be handled internally by tabster.
   */
  onNavigation?: ((event: KeyboardEvent<HTMLElement> | MouseEvent<HTMLElement, MouseEvent>, data: TreeNavigationDataParam) => void);

  /**
   * Callback fired when the component changes value from open state.
   * These property is ignored for subtrees.
   */
  onOpenChange?: ((event: KeyboardEvent<HTMLElement> | MouseEvent<HTMLElement, MouseEvent>, data: TreeOpenChangeData) => void);

  /**
   * This refers to a list of ids of opened tree items.
   * Controls the state of the open tree items.
   * These property is ignored for subtrees.
   */
  openItems?: Iterable<TreeItemValue>;

  ref?: Ref<HTMLDivElement>;

  /**
   * This refers to the selection mode of the tree.
   * - undefined: No selection can be done.
   * - 'single': Only one tree item can be selected, radio buttons are rendered.
   * - 'multiselect': Multiple tree items can be selected, checkboxes are rendered.
   * @default undefined
   */
  selectionMode?: "multiselect" | "single";

  /**
   * Size of the tree item.
   * @default 'medium'
   */
  size?: "small" | "medium";

  style?: CSSProperties;
}

FlatTree API

The FlatTree component is a variation of the Tree component that deals with a flattened data structure.

It should be used on cases where more complex interactions with a Tree is required. On simple scenarios it is advised to simply use a nested structure instead.

interface FlatTreeProps {
  /**
   * A tree item can have various appearances:
   * - 'subtle' (default): The default tree item styles.
   * - 'subtle-alpha': Minimizes emphasis on hovered or focused states.
   * - 'transparent': Removes background color.
   * @default 'subtle'
   */
  appearance?: "subtle" | "transparent" | "subtle-alpha";

  as?: "div";

  /**
   * This refers to a list of ids of checked tree items, or a list of tuples of ids and checked state.
   * Controls the state of the checked tree items.
   * These property is ignored for subtrees.
   */
  checkedItems?: Iterable<TreeItemValue | [TreeItemValue, TreeSelectionValue]>;

  children?: any;

  className?: string;

  collapseMotion?: PresenceMotionSlotProps<CollapseParams> | null;

  /**
   * Indicates how navigation between a treeitem and its actions work
   * - 'tree' (default): The default navigation, pressing right arrow key navigates inward the first inner children of a branch treeitem
   * - 'treegrid': Pressing right arrow key navigate towards the actions of a treeitem
   * @default 'tree'
   */
  navigationMode?: "tree" | "treegrid";

  /**
   * Callback fired when the component changes value from checked state.
   * These property is ignored for subtrees.
   */
  onCheckedChange?: ((event: ChangeEvent<HTMLElement>, data: TreeCheckedChangeData) => void);

  /**
   * Callback fired when navigation happens inside the component.
   * These property is ignored for subtrees.
   *
   * FIXME: This method is not ideal, as navigation should be handled internally by tabster.
   */
  onNavigation?: ((event: KeyboardEvent<HTMLElement> | MouseEvent<HTMLElement, MouseEvent>, data: TreeNavigationData_unstable) => void);

  /**
   * Callback fired when the component changes value from open state.
   * These property is ignored for subtrees.
   */
  onOpenChange?: ((event: KeyboardEvent<HTMLElement> | MouseEvent<HTMLElement, MouseEvent>, data: TreeOpenChangeData) => void);

  /**
   * This refers to a list of ids of opened tree items.
   * Controls the state of the open tree items.
   * These property is ignored for subtrees.
   */
  openItems?: Iterable<TreeItemValue>;

  ref?: Ref<HTMLDivElement>;

  /**
   * This refers to the selection mode of the tree.
   * - undefined: No selection can be done.
   * - 'single': Only one tree item can be selected, radio buttons are rendered.
   * - 'multiselect': Multiple tree items can be selected, checkboxes are rendered.
   * @default undefined
   */
  selectionMode?: "multiselect" | "single";

  /**
   * Size of the tree item.
   * @default 'medium'
   */
  size?: "small" | "medium";

  style?: CSSProperties;
}

FlatTreeItem API

The FlatTreeItem component represents a single item in a flat tree.

interface FlatTreeItemProps {
  /**
   * Defines the hierarchical level of an element within a structure.
   */
  "aria-level"?: number;

  /**
   * Defines an element's number or position in the current set of listitems or treeitems. Not required if all elements in the set are present in the DOM.
   */
  "aria-posinset"?: number;

  /**
   * Defines the number of items in the current set of listitems or treeitems. Not required if all elements in the set are present in the DOM.
   */
  "aria-setsize"?: number;

  as?: "div";

  children?: any;

  className?: string;

  /**
   * A tree item can be a leaf or a branch
   */
  itemType?: string;

  onOpenChange?: ((e: KeyboardEvent<HTMLElement> | MouseEvent<HTMLElement, MouseEvent>, data: TreeItemOpenChangeData) => void);

  /**
   * Whether the tree item is in an open state
   *
   * This overrides the open value provided by the root tree,
   * and ensure control of the visibility of the tree item per tree item.
   *
   * NOTE: controlling the open state of a tree item will not affect the open state of its children
   */
  open?: boolean;

  /**
   * This property is inferred through context on a nested tree, and required for a flat tree.
   */
  parentValue?: TreeItemValue;

  ref?: Ref<HTMLDivElement>;

  style?: (CSSProperties & { "--fluent-TreeItem--level"?: string | number; });

  /**
   * A tree item should have a well defined value, in case one is not provided by the user by this prop
   * one will be inferred internally.
   */
  value?: string | number;
}

TreeItem API

The TreeItem component represents a single item in a tree. It expects a certain order of children to work properly: the first child should be the node itself, and the second child should be a nested subtree in the form of another Tree component or a standalone TreeItem. This order follows the same order as document traversal for the TreeWalker API in JavaScript: https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker. The content and layout of a TreeItem can be defined using the TreeItemLayout or TreeItemPersonaLayout component, which should be used as a direct child of TreeItem.

When a TreeItem has nested child subtree, an expand/collapse control is displayed, allowing the user to show or hide the children.

interface TreeItemProps {
  as?: "div";

  children?: any;

  className?: string;

  /**
   * A tree item can be a leaf or a branch
   */
  itemType?: string;

  onOpenChange?: ((e: KeyboardEvent<HTMLElement> | MouseEvent<HTMLElement, MouseEvent>, data: TreeItemOpenChangeData) => void);

  /**
   * Whether the tree item is in an open state
   *
   * This overrides the open value provided by the root tree,
   * and ensure control of the visibility of the tree item per tree item.
   *
   * NOTE: controlling the open state of a tree item will not affect the open state of its children
   */
  open?: boolean;

  /**
   * This property is inferred through context on a nested tree, and required for a flat tree.
   */
  parentValue?: TreeItemValue;

  ref?: Ref<HTMLDivElement>;

  style?: (CSSProperties & { "--fluent-TreeItem--level"?: string | number; });

  /**
   * A tree item should have a well defined value, in case one is not provided by the user by this prop
   * one will be inferred internally.
   */
  value?: TreeItemValue;
}

TreeItemLayout API

The TreeItemLayout component is used as a child of TreeItem to define the content and layout of a tree item. It provides a consistent visual structure for tree items in a Tree component. This component should only be used as a direct child of TreeItem.

interface TreeItemLayoutProps {
  /**
   * Actionable elements are normally buttons, menus, or other focusable elements.
   * Those elements are only visibly available if the given tree item is currently active.
   *
   * `actions` and `aside` slots are positioned on the exact same spot,
   * so they won't be visible at the same time.
   * `aside` slot is visible by default meanwhile `actions` slot are only visible when the tree item is active.
   *
   * `actions` slot supports a `visible` prop to force visibility of the actions.
   */
  actions?: WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; } & { visible?: boolean | undefined; onVisibilityChange?: EventHandler<TreeItemLayoutActionVisibilityChangeData> | undefined; }> | null | undefined;

  as?: "div";

  /**
   * Aside content is normally used to render a badge or other non-actionable content
   */
  aside?: WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  children?: any;

  className?: string;

  /**
   * Expand icon slot,
   * by default renders a chevron icon to indicate opening and closing
   */
  expandIcon?: WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * Icon slot that renders right after main content
   */
  iconAfter?: WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * Icon slot that renders right before main content
   */
  iconBefore?: WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * Content. Children of the root slot are automatically rendered here
   */
  main?: NonNullable<WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | null> | undefined;

  ref?: Ref<HTMLDivElement>;

  selector?: (Omit<ComponentProps<Partial<CheckboxSlots>, "input">, "defaultChecked" | "onChange" | "size" | "checked"> & { checked?: boolean | "mixed"; children?: undefined; defaultChecked?: boolean | "mixed"; labelPosition?: "before" | "after" | undefined; onChange?: ((ev: ChangeEvent<HTMLInputElement>, data: CheckboxOnChangeData) => void) | undefined; shape?: "circular" | "square" | undefined; size?: "medium" | "large" | undefined; } & RefAttributes<HTMLInputElement>) | (Omit<ComponentProps<Partial<RadioSlots>, "input">, "onChange" | "size"> & { value?: string | undefined; labelPosition?: "below" | "after" | undefined; disabled?: boolean | undefined; onChange?: ((ev: ChangeEvent<HTMLInputElement>, data: RadioOnChangeData) => void) | undefined; } & RefAttributes<HTMLInputElement>) | null | undefined;

  style?: CSSProperties;
}

TreeItemPersonaLayout API

The TreeItemPersonaLayout component is used as a child of TreeItem to display a TreeItem with a media (typically an avatar) and a description. It provides a more visually appealing representation of a TreeItem and is typically used to display a list of people or topics. This component should only be used as a direct child of TreeItem.

interface TreeItemPersonaLayoutProps {
  /**
   * Actionable elements are normally buttons, menus, or other focusable elements.
   * Those elements are only visibly available if the given tree item is currently active.
   *
   * `actions` and `aside` slots are positioned on the exact same spot,
   * so they won't be visible at the same time.
   * `aside` slot is visible by default meanwhile `actions` slot are only visible when the tree item is active.
   *
   * `actions` slot supports a `visible` prop to force visibility of the actions.
   */
  actions?: WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; } & { visible?: boolean | undefined; onVisibilityChange?: EventHandler<TreeItemLayoutActionVisibilityChangeData> | undefined; }> | null | undefined;

  as?: "div";

  /**
   * Aside content is normally used to render a badge or other non-actionable content
   */
  aside?: WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  children?: any;

  className?: string;

  /**
   * Secondary text that describes or complements the content
   */
  description?: WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * Expand icon slot,
   * by default renders a chevron icon to indicate opening and closing
   */
  expandIcon?: WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * Content. Children of the root slot are automatically rendered here
   */
  main?: NonNullable<WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | null> | undefined;

  /**
   * Avatar to display.
   */
  media?: NonNullable<WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | null> | undefined;

  ref?: Ref<HTMLDivElement>;

  selector?: (Omit<ComponentProps<Partial<CheckboxSlots>, "input">, "defaultChecked" | "onChange" | "size" | "checked"> & { checked?: boolean | "mixed"; children?: undefined; defaultChecked?: boolean | "mixed"; labelPosition?: "before" | "after" | undefined; onChange?: ((ev: ChangeEvent<HTMLInputElement>, data: CheckboxOnChangeData) => void) | undefined; shape?: "circular" | "square" | undefined; size?: "medium" | "large" | undefined; } & RefAttributes<HTMLInputElement>) | (Omit<ComponentProps<Partial<RadioSlots>, "input">, "onChange" | "size"> & { value?: string | undefined; labelPosition?: "below" | "after" | undefined; disabled?: boolean | undefined; onChange?: ((ev: ChangeEvent<HTMLInputElement>, data: RadioOnChangeData) => void) | undefined; } & RefAttributes<HTMLInputElement>) | null | undefined;

  style?: CSSProperties;
}