List

an ordered list of items

Props

a11yTitle

Custom label to be used by screen readers. When provided, an aria-label will be added to the element.

string

"a user friendly label for screen readers"

action

Accepts a function that allows for a custom rendering of a component.

function

The function should be passed with an item and index of an array and return a react element.

({item, index}) => <Content />

alignSelf

How to align along the cross axis when contained in a Box or along the column axis when contained in a Grid.

string

"start"

"center"

"end"

"stretch"

"baseline"

as

The DOM tag or react component to use for the element.

string

The name of a component.

"ul"

function

() => {}

background

Item background.

string

"light-2"

array[string]

An array value indicates that items should have different backgrounds, modulo the array index.

["white", "light-2"]

border

Item border.

boolean

true

false

string

"horizontal"

"vertical"

"top"

"bottom"

"right"

"left"

"start"

"end"

object


{
  color: "string" | { dark: "string", light: "string" },
  side: "horizontal",
  size: "small"
}

children

Function that will be called when each data item is rendered. It will be passed three arguments, the individual data item, its index, and an object indicating the state of the item, if any. It should return a react element.

function

(item, index, { active }) => <Box>...</Box>

data

Array of data objects.

array[string]

["item1", "item2"]

array[object]

[
  { city: "Boise", state: "Idaho" },
  { city: "Fort Collins", state: "Colorado" }
]

defaultItemProps

Styling applied to all list items. Object accepts any Box props. To style a specific list item, use itemProps.

{{ background: ..., align: ... }}

disabled

Specified items will be styled as disabled. When combined with onClickItem, the onClick event is also disabled.

array

An array of strings. When data is an array of objects, the string is the value of the object's key specified by itemKey.

["item1", "item2"]

gridArea

The name of the area to place this inside a parent Grid.

string

"a parent grid area name"

itemKey

The key to apply to each item in the List.

string

The property name of a data object.

"id"

function

(item) => key-{item.id}

itemProps

Item specific background, border, and pad, keyed by data index. The background, border, and pad accept the same values as the same named properties on List.

object

{ 27: { background: ..., border: ..., pad: ... }}

margin

The amount of margin around the component.

string

"none"

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}

onActive

When provided, this is called with the index of the item that the user has either moused over or navigated to with their keyboard.

function

(index) => {}

onClickItem

When supplied, this function will be called with an event object which includes an 'item' property containing the data value associated with the clicked item and an 'index' property containing the index in 'data' of the clicked item. You should not include interactive elements, like Anchor or Button inside 'primaryKey' or 'secondaryKey' as that can cause confusion with overlapping interactive elements.

function

({ item, index }) => {}

onMore

Use this to indicate that 'data' doesn't contain all that it could. It will be called when all of the data items have been rendered. This might be used when the total number of items that could be retrieved is more than you'd want to load into the browser. 'onMore' allows you to lazily fetch more from the server only when needed.

function

() => {}

onOrder

Use this to indicate that the user should be allowed to re-order the data items. This cannot be used with 'paginate' or 'onClickItem'. The function will be called with the array of items in their new order when the user moves items via drag and drop or the move up/down controls.

function

() => {}

pad

Item padding.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"none"

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

"any CSS size"

object

An object can be specified to distinguish horizontal padding, vertical padding, and padding on a particular side.


{
  vertical: "...",
  horizontal: "...",
  top: "...",
  bottom: "...",
  left: "...",
  right: "...",
  start: "...",
  end: "..."
}

paginate

Whether to paginate the data.

boolean

true

false

object

If providing an object, any Box props or Pagination props are valid and will be used to style the underlying pagination component.

{}

pinned

Can be used with onOrder to specify items that should not change position in the List.

boolean

true

false

array

An array of numbers or strings that correspond to items in the List. Alternately, an object, where 'items' is an array that corresponds to items in the List, 'icon' is the icon to be rendered instead of Pin, 'color' is the color to be applied to the item text and icon, and 'background' which is the background color for the pinned items.

[1, 5]

['item 2']

{
   background: 'none',
   color: 'text-weak',
   icon: <Lock />,
   items: ['item 2', 'item 3']
}

primaryKey

When a string is supplied, it indicates the property in a data item object to use to get the primary content. If a function is supplied, it will be called with the current data item object and should return a React element that will be rendered as the primary content.

string

"property"

function

item => (<Text>{item.entry}</Text>)

secondaryKey

When a string is supplied, it indicates the property in a data item object to use to get the secondary content. If a function is supplied, it will be called with the current data item object and should return a React element that will be rendered as the secondary content.

string

"secondaryProperty"

function

item => (<Text>{item.entry}</Text>)

show

The index of an item or page to show.

number

If provided as a number, the index of an item to show.

object

If using paginate and provided as an object, the default page to show.

{ page: 2 }

showIndex

Whether to display the index number when using onOrder.

boolean

true

false

step

How many items to render at a time.

number

React/DOM Properties

At its core, the List component is a regular <ol> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for ol elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

global.hover.background

The background style when hovering over an interactive item.

string

A hex, name, or rgb value.

"active"

object

{ color: "active", opacity: "medium" }

global.hover.color

The text color when hovering over an interactive item.

string

A hex, name, or rgb value.

"black"

object

An object with a color for dark and light modes.

{ dark: "white", light: "black" }

list.container

When using paginate, any valid Box props for the container surrounding the List and Pagination components.

object

{ gap: "small" }

list.container.extend

Any additional style for the container surrounding the List and Pagination components.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

list.extend

Any additional style for the list.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

list.icons.down

The icon to use for the move down button in re-ordable lists.

element

<FormDown />

list.icons.up

The icon to use for the move up button in re-ordable lists.

element

<FormUp />

list.item.background

Background color for list items.

string

"background"

array[string]

["background", "background-contrast"]

list.item.border

Border for list items.

boolean

true

false

string

"horizontal"

object


{
  color: "string" | { dark: "string", light: "string" },
  side: "horizontal",
  size: "small"
}

list.item.disabled.color

Font color when disabled.

string

"status-disabled"

object

{ dark: "string", light: "string" }

list.item.disabled.cursor

CSS cursor type when disabled.

string

"default"

list.item.pad

Pad for list items.

boolean

true

false

string

"small"

object

{ horizontal: "medium", vertical: "small" }

list.item.extend

Any additional style for the list items.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

list.primaryKey

object

Primary key styling accepts any Text props.

{ weight: 'bold' }