Balance Logo
Balance
Reckon Design System
Open playroom

List

Used to render a dynamic list of items or select an item from a list of items.
Install
pnpm add @balance-web/list
Import usage
import {
List,
RadioList,
CheckList,
ItemText
} from '@balance-web/list';
  • Code
  • API

Design guidelines

  • All the items in the list must have the same content structure. For example either all the items must have a startElement or none, there shouldn't be a some items with startElement and some without it.
  • Do not use List in instances where the items can have nested items.

Primitives

This package exposes 3 list components as below:

List

Renders a list of items that can be links or buttons.

Basic Usage

<List>{/* list item primitives*/}</List>

Fills container width.

List.Item

This primitive renders a single list item that can be a link, button or be non-interactive.

Basic Usage

The content of a list item can be passed as children.

<List.Item>Title</List.Item>

startElement

Renders a ReactNode to the left of the children.

<List.Item
startElement={<EntityAvatar type="Organisation" name="Title" size="small" />}
>
Title
</List.Item>

href

Makes the list item behave like a link. Makes the entire list item a click target.

<List.Item href="#">Title</List.Item>

onClick

Makes the list item behave like a button. Makes the entire list item a click target.

<List.Item onClick={() => alert('Clicked')}>Title</List.Item>

endElement

Renders a ReactNode to the right of children.

<List.Item endElement={<Badge label="Active" tone="positive" />}>
Title
</List.Item>

selected

Optionally mark interactive elements (elements with href or onClick) as selected.

<List.Item
href="#"
endElement={<Badge label="Active" tone="positive" />}
selected
>
Title
</List.Item>

disabled

List item can be marked as disabled.

<List.Item
endElement={<Badge label="Disabled" tone="neutral" />}
isDisabled={true}
>
Title
</List.Item>

Non-interactive items

A list item is not interactive if neither of the href or onClick props are provided. Non-interactive items may be used for items that require a custom action so that it may stand out from the rest of the items.

<List.Item>I'm not interactive</List.Item>

Check this example for more details.

RadioList

Renders a list of items as a radio group, allowing the user to select a single item from that list.

Fills container width.

Basic Usage

const [value, setValue] = useState('');
<RadioList value={value} onChange={setValue}>
<RadioList.Item value="1">Item 1</RadioList.Item>
<RadioList.Item value="2">Item 2</RadioList.Item>
</RadioList>;

value

The value of the radio group.

onChange

Sets the new value of the radio group when the user makes a selection.

RadioList.Item

Renders a single list item as a radio input.

Basic Usage

The content of a radio item can be passed as children.

<RadioList.Item value="1">Item 1</RadioList.Item>

value

The value of the list item. This is the value that will be emitted to the onChange handler in <RadioList />

startElement

Renders a ReactNode to the left of the children.

<RadioList.Item
value="1"
startElement={<EntityAvatar type="Organisation" name="Title" size="small" />}
>
Item 1
</RadioList.Item>

CheckList

Renders a list of items as checkboxes, allowing the user to make multiple selections.

Basic Usage

const [values, setValues] = useState < Array < string >> [];
const createOnChangeHandle = (value: string) => {
return (event: React.ChangeEvent<HTMLInputElement>) => {
const checked = event.target.checked;
if (!checked) {
setValues((values) => values.filter((v) => v !== value));
} else {
setValues((values) => [...values, value]);
}
};
};
return (
<CheckList>
<CheckList.Item
checked={values.includes('1')}
onChange={createOnChangeHandle('1')}
>
Item 1
</CheckList.Item>
<CheckList.Item
checked={values.includes('2')}
onChange={createOnChangeHandle('2')}
>
Item 2
</CheckList.Item>
</CheckList>
);

CheckList.Item

Renders a single list item as a checkbox input.

Basic Usage

The contents of a checkbox item can be passed as children.

<CheckList.Item checked={true} onChange={() => {}}>
Item 1
</CheckList.Item>

checked

Sets the checkbox item to be selected or unselected.

startElement

Renders a ReactNode to the left of the children.

<CheckList.Item
startElement={<EntityAvatar type="Organisation" name="Title" size="small" />}
>
Item 1
</CheckList.Item>

ItemText

Used to render text to the body of an item. It covers the most common text combinations, it's always an option to opt out of this primitive in favor of custom text composition.

Basic Usage

<ItemText title="Some Title" />

title

Sets the title of the item.

Edit in Playroom

subText

Sets the subtext of the item.

superText

Sets the superText of the item.

tone

Sets the tone of the subText if provided.

Recipes

Button list

Radio list

Checkbox list

Custom actions and item states

Disabled items

Copyright © 2024 Reckon. Designed and developed in partnership with Thinkmill.
Bitbucket logoJira software logoConfluence logo