@element-public/react-list

v1.0.0

Published

2 months ago

List component for Element React

Downloads

0High
0Medium
0Low

peon125

slowikowskiarkadiusz

arkadiusz.slowikowski

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 | ----------------- | categoryIdKey | string | categoryNameKey | string | componentPropsKey | string | dense | boolean | dividerVariant | string | groupIdKey | string | groupNameKey | string | itemIdKey | string | items | [object]|[string] | itemsKey | string | leadingBlockType | string | navigation | boolean | nonInteractive | boolean | overlineTextKey | string | primaryTextKey | string | role | string | secondaryTextKey | string | selected | showDivider | boolean | singleList | boolean | themeColor | string | trailingBlockType | string | wrapFocus | boolean | Default | Required | Description | | ---------------------------------------------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 'id' | false | Name of the key for category ID in items. | | 'categoryName' | false | Name of the key for category name in items. | | 'componentProps' | false | Name of the key for group ID in items. custom props to apply to each list item. | | false | false | Reduced height of list items. | | 'full' | false | Variant of divider padding.Accepted Values: full, padded, inset, insetPadded | | 'id' | false | Name of the key for group ID in items. | | 'groupName' | false | Name of the key for group name in items. | | 'id' | false | Name of the key for the id of the item in items. | | null | false | An array of objects to be rendered as ListItems. If items is set children will be ignored. | | 'items' | false | Name of the key for items in list schema. | | 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 | | 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. | | false | false | Use for a list that does not require interaction. | | 'overlineText' | false | Name of the key for overlineText in items. | | 'primaryText' | false | Name of the key for primaryText in items. | | '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 | | 'secondaryText' | false | Name of the key for secondaryText in items. | | string|number|object|[string]|[number]|[object] | null | false | Item or array of selected ListItems. | | true | false | Whether or not to show a divider between list items, groups, or categories. | | true | false | When true group and category lists will be treated like one list for single selection type lists. | | empty string | false | Customized background color.Accepted Values: surface, primary, secondary | | 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 | | 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

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

List Item Primary Text Render Props

List Item Secondary Text Render Props

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. |