@adactive/az-scroller

A to Z scrolling list

Made with <3 for easier touch experience.

[//]: # (Live examples here

Getting started

npm i --save @adactive/az-scroller

OR

yarn add @adactive/az-scroller

How to use

The only non-optional prop is the list you want to display. It has to be properly formatted, with the list divided in Sections, and each Section having a Header object and an Items array.

See the example below:

    import AzScroller from "@adactive/az-scroller";
    
    // ...

    const listExample = [
         {
             header: {
                 type: 'SectionHeader',
                 letter: 'A',
             },
             items: [
                 { text: 'ABEL' },
                 { text: 'ABRAHAM' },
                 { text: 'ACHILLE' },
                 { text: 'ADAM' },
                 { text: 'ADÈLE' },
                 { text: 'ADELINE' },
                 { text: 'ADOLPHE' },
                 { text: 'ANTOINE' },
             ],
         },
         {
             header: {
                 type: 'SectionHeader',
                 letter: 'B',
             },
             items: [
                 { text: 'BAPTISTE' },
                 { text: 'BARBARA' },
                 { text: 'BARNABÉ' },
                 { text: 'BARTHÉLÉMY' },
                 { text: 'BASILE' },
             ],
         },
         {
             header: {
                 type: 'SectionHeader',
                 letter: 'C',
             },
             items: [
                 { text: 'CERISE' },
                 { text: 'CÉSAIRE' },
                 { text: 'CHARLES' },
                 { text: 'CHARLOT' },
                 { text: 'CHRISTIAN' },
             ],
         },
         {
             header: {
                 type: 'SectionHeader',
                 letter: 'E',
             },
             items: [
                 { text: 'ESTELLE' },
                 { text: 'ETHAN' },
                 { text: 'ÉTIENNE' },
                 { text: 'EUGÈNE' },
             ],
         },
         {
             header: {
                 type: 'SectionHeader',
                 letter: 'M',
             },
             items: [
                 { text: 'MICHÈLE' },
                 { text: 'MOROINE' },
                 { text: 'MURIELLE' },
                 { text: 'MYLÈNE' },
             ],
         },
         {
             header: {
                 type: 'SectionHeader',
                 letter: 'S',
             },
             items: [
                 { text: 'SEBASTIAN' },
                 { text: 'SEREN' },
                 { text: 'STANLEY' },
                 { text: 'STÉPHANE' },
                 { text: 'SYBILLE' },
                 { text: 'SYLVAIN' },
             ],
         },
         {
             header: {
                 type: 'SectionHeader',
                 letter: 'W',
             },
             items: [
                 { text: 'WANDY' },
                 { text: 'WAN' },
                 { text: 'WREN' },
                 { text: 'WILGELM' },
                 { text: 'WADE' },
                 { text: 'WILLIAM' },
                 { text: 'WINOC' },
             ],
         },
     ];
    
    <AzScroller list={listExample} />

The Header object must have a type: 'SectionHeader' and a letter: 'anyString' field, those are mandatory. Plus, you must NOT use a letter field in any Items.

Else, in the Header and the Items you can tweak the other fields and name them as you want, add fields, etc. You will be able to retrieve those fields in the renderListItem & renderListSectionHeader render methods.

Optional props

type PropsType = {|
  list: ListType,
  renderSectionItem?: ?(item: SectionItemType, key: string | number) => React.Node,
  renderSectionHeader?: ?(header: SectionHeaderType, key: string | number) => React.Node,
  shouldShowSectionHeaders?: boolean,
  sectionItemHeight?: ?number,
  sectionHeaderHeight?: ?number,
  wrapperClassNames?: Array<string>,
  wrapperStyle?: ?CSSStyleDeclaration,
  listClassNames?: Array<string>,
  listStyle?: ?CSSStyleDeclaration,
  alphabetListClassNames?: Array<string>,
  alphabetListStyle?: ?CSSStyleDeclaration,
  letterClassNames?: Array<string>,
  letterStyle?: ?CSSStyleDeclaration,
  letterHighlightedClassNames?: Array<string>,
  letterHighlightedStyle?: ?CSSStyleDeclaration,
|};

list

The list of items to scroll through.

renderSectionItem

A function, which you should provide and which will be called for each listItem. Should return a JSX component.

renderSectionHeader

Same as renderSectionItem, but the purpose is to render list section headers.

shouldShowSectionHeaders

Shows if you need to display each section height, or you need just a list without any headers.

sectionItemHeight & sectionHeaderHeight

Should be provided to assure a smooth scrolling experience. The easiest way to do that is to set a fixed height in the 2 render methods and pass them as props here as well (see Default Props section for an example). If you pass render methods, don't forget to pass the corresponding height, else default height from default props will be used, which can lead to UI issues. For more indormations on the topic, take a look at react-list package which is used here: https://www.npmjs.com/package/react-list

listClassNames & listStyle

Modify the style of list wrapper element either with CSS classnames or inline style object, or both.

alphabetListClassNames & alphabetListStyle

Modify the style of wrapper of alphabetList either with CSS classnames or inline style object, or both.

letterClassNames & letterStyle

Modify the style of each letter in alphabetList either with CSS classnames or inline style object, or both.

letterHighlightedClassNames & letterHighlightedStyle

Modify the style of the highlighted letter in alphabetList either with CSS classnames or inline style object, or both.

Note that classnames props are an array of strings (one string for each classname you want to pass) and not a single string with spaces. So if you want to pass only one classname 'letter-class-name' to letter for example, you must pass

<AzScroller
    list={listExample}
    letterClassNames={["letter-class-name"]}
/>

Exported Types

export type SectionItemType = Object;
export type SectionHeaderType = {
  type: 'SectionHeader',
  letter: string,
};
export type ListSectionType = {|
    header: SectionHeaderType,
    items: Array<SectionItemType>,
|};
export type ListType = Array<ListSectionType>;

Default props

static defaultProps = {
    renderSectionItem: (item: SectionItemType, key: string | number) => (
        <div
            key={key}
            style={{
                boxSizing: 'border-box',
                height: '30px',
                padding: '10px 20px',
            }}
        >
            {item.text}
        </div>
    ),
    renderSectionHeader: (header: SectionHeaderType, key: string | number) => (
        <div
            key={key}
            style={{
                boxSizing: 'border-box',
                height: '50px',
                padding: '20px 20px',
                fontWeight: 'bold',
                backgroundColor: 'lightgrey',
            }}
        >
            {header.letter}
        </div>
    ),
    shouldShowSectionHeaders: false,
    sectionItemHeight: null,
    sectionHeaderHeight: null,
    wrapperClassNames: [],
    wrapperStyle: null,
    listClassNames: [],
    listStyle: null,
    alphabetListClassNames: [],
    alphabetListStyle: null,
    letterClassNames: [],
    letterStyle: null,
    letterHighlightedClassNames: [],
    letterHighlightedStyle: null,
};

static defaultStyleProps = {
    wrapperStyle: {
        boxSizing: 'border-box',
        width: '500px',
        height: '500px',
        display: 'flex',
        flexDirection: 'column',
        justifyContent: 'space-between',
    },
    listStyle: {
        overflow: 'auto',
        maxHeight: '80%',
    },
    alphabetListStyle: {
        boxSizing: 'border-box',
        width: '100%',
        display: 'flex',
        justifyContent: 'space-between',
        alignItems: 'center',
        padding: '20px 10px',
    },
    letterStyle: {
        outline: 'none',
    },
    letterHighlightedStyle: {
        color: 'red',
        fontWeight: 'bold',
    },
};

Default style props will apply if:

• of course the corresponding style prop is not passed
• AND the corresponding classnames prop is not passed

This means that passing a classname or a inline style object will desactivate the corresponding default style

Copy component inside your project src folder

It will copy the component inside your project, in src/adsum-az-scroller.

npx @adactive/az-scroller copy