NestedListView

The Nested ListView is a collection of items that can be nested to create a parent/child relationship. Each item has a primary piece of information and action, one or multiple secondary actions, and associated metadata about the primary piece of information.

React

draft

Docs|Storybook|Source

Props

NestedListView

Name	Default	Description
header		`React.ReactElement<({ title, completionPill, assistiveAnnouncement, sectionFilters, children, className, actionBarClassName, onToggleSelectAll, actions, actionsLabel, ...actionBarProps }: NestedListViewHeaderProps) => React.JSX.Element, string \| React.JSXElementConstructor<any>>` An optional element to contain bulk actions, a 'Select all' checkbox, etc.
isSelectable		`boolean` Controls item's selection mode; bulk actions are allowed if true. Defaults to not selectable.
singularUnits		`string` What a single list item should be called. Used to customize assistive text about how many list items are selected. Defaults to 'list item'.
pluralUnits		`string` What many list items are called. Used to customize assistive text about how many list items are selected. Defaults to 'list items'.
ariaLabelledBy		`string` Optional ID of an element that labels the Nested List View. When provided, this takes the place of the default sr-only title.
listRef		`React.MutableRefObject<HTMLUListElement>`
isCollapsible		`boolean` Optional parameter to determine whether the Nested List View is collapsible from the header component
isReadOnly		`boolean`
className		`string`
dragAndDropProps		`{ onDrop: (args: OnDropArgs<string>) => void; renderOverlay: (dragMetadata: { id: string; title: string; }, index: number) => React.ReactElement<any, string \| React.JSXElementConstructor<any>>; items: { id: string; title: string; }[]; }` Optional callback for drag and drop
totalCount Required
selectedCount Required

NestedListViewCompletionPill

Name	Default	Description
progress Required		`Progress`

NestedListItemActionBar

Name	Default	Description
anchorIcon		`Icon` Override the icon used in the button that opens the action menu. Defaults to KebabHorizontalIcon.
label		`GitHubUiActionBarProps`
className		`string`

NestedListItemDescription

Name	Default	Description
className		`string`

NestedListItemLeadingBadge

Name	Default	Description
variant Required
size Required
title Required		`string` Text that is shown as a visible Primer Label and as visually hidden text for screen readers.
href		`string` The link that will be opened when the item is clicked
className		`string` Container class name.
color		`ColorName`

NestedListItemLeadingContent

Name	Default	Description
className		`string`

NestedListItemLeadingVisual

Name	Default	Description
icon		`OcticonProps` The Octicon component representing the desired icon
children		`React.ReactNode` Render any child content as the leading visual NOTE: if both icon and children are passed, the icon will be rendered first, with the children appended after
color		`string` The name of the Primer variable that will be used for the icon's fill eg.: var(--fgColor-done)
description		`string` A text description of the item Used for visually hidden text to describe the item on focus for the screen readers
newActivity		`boolean` Indicates whether the rendered item has new content since lastViewed
className		`string`

NestedListItemMainContent

Name	Default	Description
children		`React.ReactNode`

NestedListItemMetadata

Name	Default	Description
alignment		`"left" \| "right"` Controls how the metadata will be aligned inside the trailing content. Defaults to 'left'.
variant		`"primary" \| "secondary"` Alter the appearance of the metadata to appear more subtle than other ListItem content ('secondary', default) or comparable to other ListItem content ('primary'). Affects text color, font size, width, and distance from other metadata items.

NestedListItem

Name	Default	Description
isSelected		`boolean`
isActive		`boolean`
onSelect		`(isSelected: boolean) => void`
onKeyDown		`(event: React.KeyboardEvent<HTMLLIElement>) => void`
onFocus		`(event: React.FocusEvent<HTMLLIElement, Element>) => void`
subItemsCount		`number` Optional. Show an expand icon to indicating that the list item has additional sub items to show.
subItems		`React.ReactElement<({ children, isSelected, onSelect, ...rest }: React.PropsWithChildren<NestedListItemProps>) => JSX.Element, string \| React.JSXElementConstructor<any>>[]` Optional. Nested sub items that will be rendered when the sub tree is expanded.
loadSubItems		`() => void` Optional. Callback for loading sub items
defaultExpanded		`boolean` Optional. The expanded state of the item when it is initially rendered. Use to control the state.
className		`string` List Item's inner container class name
metadataContainerClassName		`string` Metadata Container class name
dragAndDropProps		`{ showTrigger?: boolean; isOverlay?: boolean; itemId?: string; }`
title Required		`React.ReactElement<typeof NestedListItemTitle, string \| React.JSXElementConstructor<any>>` A NestedListItem title communicates the overall purpose of the NestedListItem.
metadata		`MetadataContainerProps` Optional extra elements to display on the right side of the list item. You can optionally wrap individual pieces of content in `NestedListItem.Metadata` for a consistent appearance.
secondaryActions		`React.ReactElement<typeof NestedListItemActionBar, string \| React.JSXElementConstructor<any>>` Optional menu of additional actions to be shown on the right side of the NestedListItem. Use `NestedListItem.ActionBar`.
children		`React.ReactNode` Other content.

NestedListItemTitle

Name	Default	Description
containerClassName		`string`
leadingBadge		`React.ReactElement<typeof NestedListItemLeadingBadge, string \| React.JSXElementConstructor<any>>`
trailingBadges		`React.ReactElement<({ title, className, children, ...props }: NestedListItemTrailingBadgeProps) => React.JSX.Element, string \| React.JSXElementConstructor<any>>[]`
anchorClassName		`string`
anchorRef		`React.ForwardedRef<HTMLAnchorElement>` A ref to the anchor element
href		`string` The link that will be opened when the item is clicked
additionalLinkProps		`Omit<any, "ref">`
onClick		`React.MouseEventHandler<HTMLElement>` A click handler to be executed when the element is clicked
tooltip		`string` The tooltip to add context to the title
value Required		`string` The text content of the header, to convey the primary meaning of the list item.

NestedListItemTrailingBadge

Name	Default	Description
variant Required
size Required
title		`string` Text that is shown as a visible Primer Label and as visually hidden text for screen readers.
className		`string` Container class name.

NestedListViewHeader

Name	Default	Description
title		`React.ReactElement<({ title, children, className, scrollToOnCollapseOffset, }: NestedListViewHeaderTitleProps) => React.JSX.Element, string \| React.JSXElementConstructor<any>>` The rendered title of the list or information regarding its contents.
completionPill		`React.ReactElement<typeof NestedListViewCompletionPill, string \| React.JSXElementConstructor<any>>` Display completed & total issue information about the issues contained in the NestedListView
sectionFilters		`any` Links for applying any categorical, mutually exclusive section filters for the content of the NestedListView.
assistiveAnnouncement		`string` Used for assistive announcements that are reflective of the visual updates to the list container a sighted user will experience when using the list. Defaults to no announcement. Visually hidden, for screenreaders only.
onToggleSelectAll		`(isSelectAllChecked: boolean) => void` Callback for when the checkbox for selecting and deselecting all list items is toggled.
children		`React.ReactNode` Optional additional actions to show. Will not fall into an overflow dropdown menu to accommodate small screen widths.
className		`string` Container class name.
actionBarClassName		`string` Action Bar container class name.

NestedListViewHeaderSectionFilterLink

Name	Default	Description
title Required		`string` The name of this section filter, e.g., "Open" to describe a section filter that shows only open issues.
count		`React.ReactNode` The number of list items in the category this section filter represents. Optional. Changes appearance when `isLoading` is true.
href Required		`string` The URL to load the list with only items matching this section filter.
isSelected		`boolean` Optionally specify whether this section filter is currently active. Defaults to not being selected.
isLoading		`boolean` Optionally specify whether the section filter is still being loaded. Will be used to style the count, if given, when true.
className		`string`

NestedListViewHeaderTitle

Name	Default	Description
title Required		`string`
children		`React.ReactNode`
className		`string`
onSetExpanded		`(isExpanded: boolean) => void`
scrollToOnCollapseOffset		`number` The offset from the top to scroll to after collapsing

NestedListView

Internal Component