paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 39 Packages Projects Releases Wiki Activity

feat(ui): add ListBox and ListBoxItem components

Browse Source 
Adds standalone `ListBox` and `ListBoxItem` components to `@backstage/ui`,
built on top of React Aria's ListBox primitives. Items support icons,
descriptions, and single or multiple selection modes.

Includes Storybook stories and docs-ui documentation page.

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
Made-with: Cursor
This commit is contained in:
Charles de Dreuille
2026-03-14 14:37:33 +00:00
parent 6f01c33a0e
commit 04d9d8df40
14 changed files with 913 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/ui/src/components/ListBox/ListBox.module.css
+106
View File
@@ -0,0 +1,106 @@
/*
* Copyright 2025 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
@layer tokens, base, components, utilities;
@layer components {
.bui-ListBox {
box-sizing: border-box;
overflow-y: auto;
outline: none;
&:focus-visible {
outline: none;
}
}
.bui-ListBoxItem {
box-sizing: border-box;
display: flex;
align-items: center;
gap: var(--bui-space-2);
padding-block: var(--bui-space-2);
padding-inline: var(--bui-space-3);
border-radius: var(--bui-radius-2);
font-size: var(--bui-font-size-3);
font-family: var(--bui-font-regular);
color: var(--bui-fg-primary);
cursor: pointer;
user-select: none;
outline: none;
&[data-hovered] {
background-color: var(--bui-bg-neutral-2);
}
&[data-focus-visible] {
background-color: var(--bui-bg-neutral-2);
}
&[data-selected] {
.bui-ListBoxItemCheck {
opacity: 1;
}
}
&[data-disabled] {
cursor: not-allowed;
color: var(--bui-fg-disabled);
}
}
.bui-ListBoxItemCheck {
display: flex;
align-items: center;
justify-content: center;
flex-shrink: 0;
opacity: 0;
transition: opacity 0.2s ease-in-out;
width: 1rem;
height: 1rem;
& svg {
width: 1rem;
height: 1rem;
}
}
.bui-ListBoxItemIcon {
display: flex;
align-items: center;
justify-content: center;
flex-shrink: 0;
color: var(--bui-fg-secondary);
& svg {
width: 1rem;
height: 1rem;
}
}
.bui-ListBoxItemLabel {
flex: 1;
display: flex;
flex-direction: column;
gap: var(--bui-space-1);
min-width: 0;
}
.bui-ListBoxItemDescription {
font-size: var(--bui-font-size-2);
color: var(--bui-fg-secondary);
}
}
packages/ui/src/components/ListBox/ListBox.stories.tsx
+180
View File
@@ -0,0 +1,180 @@
/*
* Copyright 2025 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import preview from '../../../../../.storybook/preview';
import { useState } from 'react';
import { ListBox, ListBoxItem } from './ListBox';
import type { Selection } from 'react-aria-components';
import {
RiJavascriptLine,
RiReactjsLine,
RiShipLine,
RiTerminalLine,
RiCodeLine,
} from '@remixicon/react';
const meta = preview.meta({
title: 'Backstage UI/ListBox',
component: ListBox,
args: {
style: { width: 280 },
'aria-label': 'List',
},
});
const items = [
{ id: 'react', label: 'React' },
{ id: 'typescript', label: 'TypeScript' },
{ id: 'javascript', label: 'JavaScript' },
{ id: 'rust', label: 'Rust' },
{ id: 'go', label: 'Go' },
];
const itemsWithDescription = [
{
id: 'react',
label: 'React',
description: 'A JavaScript library for building user interfaces',
},
{
id: 'typescript',
label: 'TypeScript',
description: 'Typed superset of JavaScript',
},
{
id: 'javascript',
label: 'JavaScript',
description: 'The language of the web',
},
{
id: 'rust',
label: 'Rust',
description: 'Systems programming with memory safety',
},
{
id: 'go',
label: 'Go',
description: 'Simple, fast, and reliable',
},
];
const itemIcons: Record<string, React.ReactNode> = {
react: <RiReactjsLine />,
typescript: <RiCodeLine />,
javascript: <RiJavascriptLine />,
rust: <RiShipLine />,
go: <RiTerminalLine />,
};
export const Default = meta.story({
render: args => (
<ListBox {...args}>
{items.map(item => (
<ListBoxItem key={item.id} id={item.id}>
{item.label}
</ListBoxItem>
))}
</ListBox>
),
});
export const WithIcons = meta.story({
render: args => (
<ListBox {...args}>
{items.map(item => (
<ListBoxItem key={item.id} id={item.id} icon={itemIcons[item.id]}>
{item.label}
</ListBoxItem>
))}
</ListBox>
),
});
export const WithDescription = meta.story({
args: {
style: { width: 340 },
},
render: args => (
<ListBox {...args}>
{itemsWithDescription.map(item => (
<ListBoxItem
key={item.id}
id={item.id}
icon={itemIcons[item.id]}
description={item.description}
>
{item.label}
</ListBoxItem>
))}
</ListBox>
),
});
export const SelectionModeSingle = meta.story({
render: args => {
const [selected, setSelected] = useState<Selection>(new Set(['react']));
return (
<ListBox
{...args}
selectionMode="single"
selectedKeys={selected}
onSelectionChange={setSelected}
>
{items.map(item => (
<ListBoxItem key={item.id} id={item.id}>
{item.label}
</ListBoxItem>
))}
</ListBox>
);
},
});
export const SelectionModeMultiple = meta.story({
render: args => {
const [selected, setSelected] = useState<Selection>(
new Set(['react', 'typescript']),
);
return (
<ListBox
{...args}
selectionMode="multiple"
selectedKeys={selected}
onSelectionChange={setSelected}
>
{items.map(item => (
<ListBoxItem key={item.id} id={item.id}>
{item.label}
</ListBoxItem>
))}
</ListBox>
);
},
});
export const Disabled = meta.story({
render: args => (
<ListBox {...args} disabledKeys={['typescript', 'rust']}>
{items.map(item => (
<ListBoxItem key={item.id} id={item.id}>
{item.label}
</ListBoxItem>
))}
</ListBox>
),
});
packages/ui/src/components/ListBox/ListBox.tsx
+79
View File
@@ -0,0 +1,79 @@
/*
* Copyright 2025 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import {
ListBox as RAListBox,
ListBoxItem as RAListBoxItem,
Text,
} from 'react-aria-components';
import { RiCheckLine } from '@remixicon/react';
import { useDefinition } from '../../hooks/useDefinition';
import { ListBoxDefinition, ListBoxItemDefinition } from './definition';
import type { ListBoxProps, ListBoxItemProps } from './types';
/**
* A listbox displays a list of options and allows a user to select one or more of them.
*
* @public
*/
export const ListBox = <T extends object>(props: ListBoxProps<T>) => {
const { ownProps, restProps } = useDefinition(ListBoxDefinition, props);
const { classes, items, children, renderEmptyState } = ownProps;
return (
<RAListBox
className={classes.root}
items={items}
renderEmptyState={renderEmptyState}
{...restProps}
>
{children}
</RAListBox>
);
};
/**
* An item within a ListBox.
*
* @public
*/
export const ListBoxItem = (props: ListBoxItemProps) => {
const { ownProps, restProps } = useDefinition(ListBoxItemDefinition, props);
const { classes, children, description, icon } = ownProps;
const textValue = typeof children === 'string' ? children : undefined;
return (
<RAListBoxItem
textValue={textValue}
className={classes.root}
{...restProps}
>
<div className={classes.check}>
<RiCheckLine />
</div>
{icon && <span className={classes.icon}>{icon}</span>}
<div className={classes.label}>
<Text slot="label">{children}</Text>
{description && (
<Text slot="description" className={classes.description}>
{description}
</Text>
)}
</div>
</RAListBoxItem>
);
};
packages/ui/src/components/ListBox/definition.ts
+57
View File
@@ -0,0 +1,57 @@
/*
* Copyright 2025 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { defineComponent } from '../../hooks/useDefinition';
import type { ListBoxOwnProps, ListBoxItemOwnProps } from './types';
import styles from './ListBox.module.css';
/**
* Component definition for ListBox
* @public
*/
export const ListBoxDefinition = defineComponent<ListBoxOwnProps>()({
styles,
classNames: {
root: 'bui-ListBox',
},
propDefs: {
items: {},
children: {},
renderEmptyState: {},
className: {},
},
});
/**
* Component definition for ListBoxItem
* @public
*/
export const ListBoxItemDefinition = defineComponent<ListBoxItemOwnProps>()({
styles,
classNames: {
root: 'bui-ListBoxItem',
check: 'bui-ListBoxItemCheck',
icon: 'bui-ListBoxItemIcon',
label: 'bui-ListBoxItemLabel',
description: 'bui-ListBoxItemDescription',
},
propDefs: {
children: {},
description: {},
icon: {},
className: {},
},
});
packages/ui/src/components/ListBox/index.ts
+24
View File
@@ -0,0 +1,24 @@
/*
* Copyright 2025 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export { ListBox, ListBoxItem } from './ListBox';
export type {
ListBoxProps,
ListBoxOwnProps,
ListBoxItemProps,
ListBoxItemOwnProps,
} from './types';
export { ListBoxDefinition, ListBoxItemDefinition } from './definition';
packages/ui/src/components/ListBox/types.ts
+71
View File
@@ -0,0 +1,71 @@
/*
* Copyright 2025 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import type {
ListBoxProps as ReactAriaListBoxProps,
ListBoxItemProps as ReactAriaListBoxItemProps,
} from 'react-aria-components';
/**
* Own props for the ListBox component.
*
* @public
*/
export type ListBoxOwnProps<T = object> = {
items?: ReactAriaListBoxProps<T>['items'];
children?: ReactAriaListBoxProps<T>['children'];
renderEmptyState?: ReactAriaListBoxProps<T>['renderEmptyState'];
className?: string;
};
/**
* Props for the ListBox component.
*
* @public
*/
export interface ListBoxProps<T>
extends ListBoxOwnProps<T>,
Omit<ReactAriaListBoxProps<T>, keyof ListBoxOwnProps<T>> {}
/**
* Own props for the ListBoxItem component.
*
* @public
*/
export type ListBoxItemOwnProps = {
/**
* The main label content of the item.
*/
children?: React.ReactNode;
/**
* Optional secondary description text.
*/
description?: string;
/**
* Optional icon displayed before the label.
*/
icon?: React.ReactNode;
className?: string;
};
/**
* Props for the ListBoxItem component.
*
* @public
*/
export interface ListBoxItemProps
extends ListBoxItemOwnProps,
Omit<ReactAriaListBoxItemProps, keyof ListBoxItemOwnProps> {}
packages/ui/src/definitions.ts
+4
View File
@@ -48,6 +48,10 @@ export {
HeaderPageDefinition,
} from './components/Header/definition';
export { LinkDefinition } from './components/Link/definition';
export {
ListBoxDefinition,
ListBoxItemDefinition,
} from './components/ListBox/definition';
export { MenuDefinition } from './components/Menu/definition';
export { PasswordFieldDefinition } from './components/PasswordField/definition';
export { PopoverDefinition } from './components/Popover/definition';
packages/ui/src/index.ts
+1
View File
@@ -53,6 +53,7 @@ export * from './components/Menu';
export * from './components/Popover';
export * from './components/SearchField';
export * from './components/Link';
export * from './components/ListBox';
export * from './components/Select';
export * from './components/Skeleton';
export * from './components/Switch';