Listbox

Renders a list of options in an accessible way. A Listbox widget presents a list of options and allows a user to select one of them.

install	version	usage	style
yarn add @ciceksepeti/cui-listbox	0.0.13	import {Listbox, ListboxItem } from '@ciceksepeti/cui-listbox'	import '@ciceksepeti/cui-listbox/style.css'

Wai-AriaW3

RepositoryGitHub

PackageNPM

StyleSass

Content

Renders list of elements. Listbox is a polymorphic component. That's why can be rendered as any valid HTML tag

Examples

Default

Example of the default behavior of Listbox component that controlled. Renders as 'button' by default.

note

Listbox component must use with `onChange` and `value` props together to work properly as controlled.

import React, { useState } from 'react';
import { Listbox, ListboxItem } from '@ciceksepeti/cui-listbox';
import '@ciceksepeti/cui-listbox/styles.css';

export function CUIListboxDefaultControlled() {
  let [value, setValue] = useState('apple');

  return (
    <>
      <Listbox
        value={value}
        onChange={(value) => setValue(value)}
        aria-labelledby="listbox1"
      >
        <ListboxItem value="apple">apple</ListboxItem>
        <ListboxItem value="orange">orange</ListboxItem>
        <ListboxItem value="cherry">cherry</ListboxItem>
        <ListboxItem value="banana">banana</ListboxItem>
      </Listbox>
      <p>Current State: {value}</p>
    </>
  );
}

PREVIEW

Listbox Default - Controlled

Current State: apple

Example of the default behavior of Listbox component that uncontrolled. Renders as 'button' by default.

note

If you want to use the Listbox component as uncontrolled, should be used ListboxInput component has ref to catch the selected value of the Listbox.

import React, { useRef } from 'react';
import { Listbox, ListboxItem, ListboxInput } from '@ciceksepeti/cui-listbox';
import '@ciceksepeti/cui-listbox/styles.css';

export function CUIListboxDefaultUncontrolled() {
  const inputRef = useRef(null);

  return (
      <Listbox aria-labelledby="listbox 10">
        <ListboxInput ref={inputRef} />
        <ListboxItem value="apple">apple</ListboxItem>
        <ListboxItem value="orange">orange</ListboxItem>
        <ListboxItem value="cherry">cherry</ListboxItem>
        <ListboxItem value="banana">banana</ListboxItem>
      </Listbox>
      <button
        onClick={() => alert(inputRef.current?.value)}
        style={{ marginLeft: '1rem' }}
      >
        Submit
      </button>
  );
}

PREVIEW

Listbox Default - Uncontrolled

Prefix

Example of a Listbox component with prefix. Renders as 'button' by default.

import React from 'react';
import { Listbox, ListboxItem } from '@ciceksepeti/cui-listbox';
import '@ciceksepeti/cui-listbox/styles.css';

export function Example() {
  return (
    <Listbox
      name="listbox1"
      prefix={<span style={{ marginRight: 5 }}>#</span>}
      style={{
        width: 200,
      }}
      as="button"
      aria-labelledby="listbox2"
    >
      <ListboxItem value="item1">item 1</ListboxItem>
      <ListboxItem value="item2">item 2</ListboxItem>
      <ListboxItem value="item3">item 3</ListboxItem>
      <ListboxItem value="item4">item 4</ListboxItem>
    </Listbox>
  );
}

PREVIEW

Listbox with Prefix

Search

Example of a searchable Listbox component. Renders as 'button' by default.

import React, { useState } from 'react';
import { Listbox, ListboxItem } from '@ciceksepeti/cui-listbox';
import '@ciceksepeti/cui-listbox/styles.css';

export function Example() {
  return (
    <Listbox
      as="button"
      aria-labelledby="listbox3"
      name="listbox3"
      style={{
        width: 200,
      }}
    >
      <input
        onChange={(e) => {
          setSearch(e.target.value);
        }}
        placeholder="Search"
        style={{
          margin: '10px 0 10px 10px',
        }}
        type="text"
        value={search}
      />
      {items
        .filter(({ label }) => label.includes(search))
        .map(({ value, label }) => (
          <ListboxItem key={value} value={value}>
            {label}
          </ListboxItem>
        ))}
    </Listbox>
  );
}

PREVIEW

Listbox with Search Input

Compound

Listbox is a compound component. CactusUI provides ListboxButton, ListboxInput and ListboxPopover to user create own Listbox. Props and their required and default values of these subcomponents are described props section of the page.

import React, { useState } from 'react';
import {
  ListboxButton,
  ListboxPopover,
  ListboxInput,
  ListboxItem,
} from '@ciceksepeti/cui-listbox';
import '@ciceksepeti/cui-listbox/styles.css';

export function CUIListboxCompoundControlled() {
  const [value, setValue] = useState('orange');
  return (
    <>
      <ListboxButton
        aria-labelledby="listbox4"
        value={value}
        onChange={(value) => setValue(value)}
      >
        <ListboxPopover>
          <ListboxItem value="apple">apple</ListboxItem>
          <ListboxItem value="orange">orange</ListboxItem>
          <ListboxItem value="cherry">cherry</ListboxItem>
          <ListboxItem value="banana">banana</ListboxItem>
        </ListboxPopover>
      </ListboxButton>
      <span style={{ marginLeft: '1rem' }}>Current State : {value}</span>
    </>
  );
}

PREVIEW

Compound Listbox - Controlled

Current State : orange

import React, { useRef } from 'react';
import {
  ListboxButton,
  ListboxPopover,
  ListboxItem,
  ListboxInput,
} from '@ciceksepeti/cui-listbox';
import '@ciceksepeti/cui-listbox/styles.css';

export function CUIListboxCompoundUncontrolled() {
  const inputRef = useRef(null);
  return (
    <>
      <ListboxButton aria-labelledby="listbox4" defaultValue="banana">
        <ListboxInput ref={inputRef} />
        <ListboxPopover>
          <ListboxItem value="apple">apple</ListboxItem>
          <ListboxItem value="orange">orange</ListboxItem>
          <ListboxItem value="cherry">cherry</ListboxItem>
          <ListboxItem value="banana">banana</ListboxItem>
        </ListboxPopover>
      </ListboxButton>
      <button
        onClick={() => alert(inputRef.current?.value)}
        style={{ marginLeft: '1rem' }}
      >
        Submit
      </button>
  );
  </>
}

PREVIEW

Compound Listbox - Uncontrolled

Props

Listbox Props

Listbox Events

Listbox Accessibility

ListboxItem Props

ListboxItem Events

ListboxButton Props

ListboxButton Events

ListboxPopover Props

Playground

Styling

Element Selectors

Default Selector Values