@element-public/react-list NPM

List

Description

A list is a continuous column of rows containing text and images. List rows are composed of items containing primary and supplemental actions, which are represented by text and icons. Lists are optimized for reading comprehension and should be easy to scan quickly. Lists in Element are comprised of the following components: List and ListItem - as well as optional components such as ListDivider, ListGroup, ListGroupDivider, ListGroupSubheader.

See live demos on storybook

Storybook List Demos

Install bundle from npm-e

npm i @element-public/react-components @element-public/themes

Optional: install the component individually

npm i @element-public/react-list @element-public/themes

Open ~/.npmrc in an editor and add the following line to enable the @element-public scope:

@element-public:registry=https://npm.platforms.engineering

Troubleshooting

See below if you have never installed a package from Bayer's npm-enterprise or run into the following error:

npm ERR! code E401
npm ERR! Unable to authenticate, your authentication token seems to be invalid.
npm ERR! To correct this please trying logging in again with:
npm ERR!     npm login

Setup an access token

See the devtools npm-e guide to learn how to create an access token if this is the first time you are using a npm-e package at Bayer or you do not have a line that starts with the following in your ~/.npmrc file:

//npm.platforms.engineering/:_authToken=

Notes

Lists in Element are comprised of the following components: List and ListItem - as well as optional components, such as ListDivider, ListGroup, ListGroupDivider, ListGroupSubheader.

List Item Sections

Leading Block - Contains media or control and is shown to the left of the ListItem's main content.
- Accepted types and sizes:
  - avatar 40x40
  - Icon 24x24
  - image 56x56
  - large image 100x56
  - thumbnail 40x40
  - Checkbox
  - Radio
  - Switch
Content Block - The text of the ListItem. Has three subsections:
- Overline text appears above primary and secondary text.
- Primary text is the main text and is required.
- Secondary text appears below the primary text.
Trailing Block - Contains media or control and is shown to the right of the ListItem's main content.
- Accepted types and sizes:
  - avatar 40x40
  - Icon 24x24
  - image 56x56
  - large image 100x56
  - thumbnail 40x40
  - meta (plain text caption)
  - Checkbox
  - Radio
  - Switch

List Props

Name	Type	Default	Required	Description
categoryIdKey	string	'id'	false	Name of the key for category ID in `items`.
categoryNameKey	string	'categoryName'	false	Name of the key for category name in `items`.
componentPropsKey	string	'componentProps'	false	Name of the key for group ID in `items`. custom props to apply to each list item.
dense	boolean	false	false	Reduced height of list items.
dividerVariant	string	'full'	false	Variant of divider padding.Accepted Values: full, padded, inset, insetPadded
groupIdKey	string	'id'	false	Name of the key for group ID in `items`.
groupNameKey	string	'groupName'	false	Name of the key for group name in `items`.
itemIdKey	string	'id'	false	Name of the key for the id of the item in `items`.
items	object\|string	null	false	An array of objects to be rendered as `ListItems`. If `items` is set children will be ignored.
itemsKey	string	'items'	false	Name of the key for `items` in list schema.
leadingBlockType	string	undefined	false	The type of media that will render in the leading block of the `ListItems`. See README for size constraints. If `leadingBlockType` and `trailingBlockType` are both set to a control type (checkbox, radio or switch) `trailingBlockType` will be ignored.Accepted Values: avatar, checkbox, icon, image, lgImage, radio, switch, thumbnail
navigation	boolean	false	false	Enables support for lists of navigation links. Each list item will be rendered as an anchor element by default unless overridden via the `component` prop on each list item.
nonInteractive	boolean	false	false	Use for a list that does not require interaction.
overlineTextKey	string	'overlineText'	false	Name of the key for `overlineText` in `items`.
primaryTextKey	string	'primaryText'	false	Name of the key for `primaryText` in `items`.
role	string	'listbox'	false	The aria role of the list. For selection list use `listbox`. For menu list use `menu`. For radio list use `radiogroup`. For checkbox list use `group`. For non-interactive list do not set.Accepted Values: listbox, menu, radiogroup, group
secondaryTextKey	string	'secondaryText'	false	Name of the key for `secondaryText` in `items`.
selected	string\|number\|object\|string\|number\|object	null	false	Item or array of selected `ListItems`.
showDivider	boolean	true	false	Whether or not to show a divider between list items, groups, or categories.
singleList	boolean	true	false	When true group and category lists will be treated like one list for single selection type lists.
themeColor	string	empty string	false	Customized background color.Accepted Values: surface, primary, secondary
trailingBlockType	string	undefined	false	The type of media that will render in the trailing block of the `ListItems`. See README for size constraints. If `leadingBlockType` and `trailingBlockType` are both set to a control type (checkbox, radio or switch) `trailingBlockType` will be ignored.Accepted Values: avatar, badge, checkbox, icon, image, lgImage, meta, radio, switch, thumbnail
wrapFocus	boolean	true	false	Allows keyboard navigation to jump to the top or bottom of the list to enable continuous navigation.

List Render Props

Name	Type	Default	Required	Description
children	React.ReactNode	null	false	List content. Expects a 'ListItem'.

List Events

Name	Default	Required	Params	Description
onAction	null	false	1. Name: id, Type: number, Description: Index of activated List Item,2. Name: selectedId, Type: string\|object\|string\|object, Description: Items or array of selected items if a multi select list.,3. Name: event, Type: javascript event, Description: The javascript event	Fired when a List Item is activated.

List Breaking Changes

Description
List: Child component `ListItemGraphic` has been removed.,Child component `ListItemMeta` has been renamed to `ListItemLeadingBlock`.,Child component `ListItemText` has been removed.
avatar (removed): No longer needed
selectable (removed): Ability to select List Items will be set by the role.
threeLine (removed): No longer needed. Use `lineNumber` instead.
twoLine (removed): No longer needed. Use `lineNumber` instead.

List Divider Props

Name	Type	Default	Required	Description
variant	string	'full'	false	Variant of the divider padding.Accepted Values: full, padded, inset, insetPadded

List Divider Breaking Changes

Description
inset (removed): No longer needed. Use `variant` instead
padded (removed): No longer needed. Use `dividerVariant` instead

List Group Render Props

Name	Type	Default	Required	Description
children	React.ReactNode	null	false	Expects one or more List or ListGroupSubHeader.

List Group Subheader Render Props

Name	Type	Default	Required	Description
children	React.ReactNode	null	false	Expects a string but accepts any valid markup or components.

List Item Props

Name	Type	Default	Required	Description
activated	boolean	false	false	Alternate styling for selected interactive items without a control. Activation represents a status with more permanence (e.g., current page in a navigation list).
ariaChecked	boolean	false	false	Whether or not the list item's radio or checkbox is selected for radio or checkbox lists.
disableHighlight	boolean	false	false	Tells list item not to put selected class to add background to the list item.
disabled	boolean	false	false	Disable interaction for the ListItem within an interactive List.
isChildOption	boolean	false	false	Used with Select.
leadingBlockType	string	empty string	false	The type of media that will render in the leading block. See README for size constraints. If `leadingBlockType` is set on the parent List, it will take precedence. If `leadingBlockType` and `trailingBlockType` are both set to a control type (checkbox, radio or switch) `trailingBlockType` will be ignored.Accepted Values: avatar, checkbox, icon, image, lgImage, radio, switch, thumbnail
noHover	boolean	false	false	A hover style will not be applied.
nonInteractive	boolean	false	false	Used within a list that does not require interaction. See `disabled` for disabling an item within an interactive list.
selected	boolean	false	false	A selected style will be applied. Selection represents a choice that might change frequently (e.g., option in a list). Required by selected interactive items without a control.
tag	string\|React.ElementType\|React.Component	null	false	Component to be rendered as each list item. Normal lists use `li` elements, nav lists use `a` elements. You would use this for example if you want to use a router link component as each list item.
themeColor	string	empty string	false	Customized background color.Accepted Values: surface, primary, secondary
trailingBlockType	string	undefined	false	The type of media that will render in the trailing block. See README for size constraints. If `trailingBlockType` is set on the parent List, it will take precedence. If `leadingBlockType` and `trailingBlockType` are both set to a control type (checkbox, radio or switch) `trailingBlockType` will be ignored.Accepted Values: avatar, badge, checkbox, icon, image, lgImage, meta, radio, switch, thumbnail
variant	string	'standard'	false	Used to adjust the padding of the `ListItem` when used as a category or group header.Accepted Values: standard, category, group
wrapMode	string	'wrap'	false	Determines the text wrapping mode of the list item: `wrap` will wrap text like normal, `truncate` will truncate text with an ellipsis and `noWrap` will truncate the text by clipping.Accepted Values: wrap, noWrap, truncate

List Item Render Props

Name	Type	Default	Required	Description
children	React.ReactNode	null	false	Content to be rendered inside the list item content block. Most often a string, but accepts any valid markup. When using primaryText, secondaryText or overlineText the children will be ignored.
leadingBlock	React.ReactNode	null	false	Content to be displayed in the leading block container. See README for types supported. If a string is sent for a control type, it will used for the `name` attribute on the control. For radio type controls, send the same name for every item.
overlineText	React.ReactNode	null	false	Text that will appear above the standard text.
primaryText	React.ReactNode	null	false	Standard list text.
secondaryText	React.ReactNode	null	false	Text that will appear below the standard text.
trailingBlock	React.ReactNode	null	false	Content to be displayed in the trailing block container. See README for types supported. If a string is sent for a control type, it will used for the `name` attribute on the control. For radio type controls, send the same name for every item.
value	React.ReactNode	null	false	A custom value to be returned as the second onClick argument.

List Item Events

Name	Default	Required	Params	Description
onClick	null	false		Fired when the user clicks the ListItem. Returns the event as the first argument and any specified value as the second argument.
onKeyPress	null	false		Fired when the user presses a key down.

List Item Breaking Changes

Description
component (removed): Renamed to `tag`.
graphic (removed): No longer needed. Use `leadingBlock` instead.
largeImage (removed): List Item will handle image size by the leading or trailing block type.
meta (removed): Will now be handled by `trailingBlock`
multiline (removed): No longer supported
scrollOnSelected (removed): No longer needed.
text (removed): No longer needed. Use `primaryText` instead.

List Item Content Render Props

Name	Type	Default	Required	Description
children	React.ReactNode	null	false	Content to be rendered inside the list item primary text content block. Most often a string, but accepts any valid markup. When using primaryText, secondaryText or overlineText the children will be ignored.
overlineText	React.ReactNode	null	false	Text that will appear above the standard text.
primaryText	React.ReactNode	null	false	Standard list text. `children` may also be used but will require additional styling. Use `primaryText` instead of `children` when using overline or secondary text.
secondaryText	React.ReactNode	null	false	Text that will appear below the standard text.

List Item Leading Block Render Props

Name	Type	Default	Required	Description
children	React.ReactNode	null	false	Media or control to be rendered in the List Item's Leading Block

List Item Overline Render Props

Name	Type	Default	Required	Description
children	React.ReactNode	null	false	Expects a string but accepts any valid markup or components.

List Item Primary Text Render Props

Name	Type	Default	Required	Description
children	React.ReactNode	null	false	Expects a string but accepts any valid markup or components.

List Item Secondary Text Render Props

Name	Type	Default	Required	Description
children	React.ReactNode	null	false	Expects a string but accepts any valid markup or components.

List Item Trailing Block Render Props

Name	Type	Default	Required	Description
children	React.ReactNode	null	false	Media, control or text to be rendered in the List Item's Trailing Block

List Items List Props

Name	Type	Default	Required	Description
items	object\|string	null	false	The List Items to be rendered in the Lists. If `items` is set children will be ignored.