colist
v0.0.3
Published
[Command]() • [CommandInput]() • [CommandList]() • [CommandItem]() • [useCommand]()
Downloads
9
Readme
Command
Command • CommandInput • CommandList • CommandItem • useCommand
At the simplest, a Command looks like this:
const Example = () => {
const commandProps = useCommand()
return (
<Command
aria-label="Command menu"
dialog={false}
{...commandProps}
>
<CommandInput />
<CommandList>
<CommandItem value="No Priority">No Priority</CommandItem>
<CommandItem value="Urgent">Urgent</CommandItem>
<CommandItem value="High">High</CommandItem>
<CommandItem value="Medium">Medium</CommandItem>
<CommandItem value="Low">Low</CommandItem>
</CommandList>
</Command>
)
}
Installation
yarn add colist
import {
Command,
CommandInput,
CommandList,
CommandItem,
useCommand
} from 'colist'
Command
CSS selector:
data-command
and optionally data-command-overlay
Required props:
Pass it everything returned from useCommand
.
Optional props:
className
(string): class applied to the wrapper nodedialog
(boolean): whether to render the Command in a dialogoverlayClassName
(string): if rendered in a dialog, the class of the overlayaria-label
(string): if rendered in a dialog, the label of the dialogonDismiss
(function): if rendered in a dialog, the callback function when closedordering
(boolean): whether to automatically order items
CommandInput
Must be rendered inside a <Command>
.
CSS selector:
data-command-input
Required props: None.
Optional props:
Any props will be spread to the <input />
element. Also forwards ref
.
CommandList
Must be rendered inside a <Command>
.
CSS selector:
data-command-list
and data-command-list-empty
Required props: None.
Optional props:
Any props will be spread to the <ul />
element. Also forwards ref
.
CommandItem
Must be rendered inside a <CommandList>
CSS selector:
data-command-item
and aria-selected
when active
Required props:
value
(string): string to compare against for filtering and ordering
Optional props:
callback
(function): what to execute on click or selection
All other props will be made available on commandProps.map.current
useCommand
const commandProps = useCommand(defaults)
Automatically handles all logic and state for efficiently rendering, filtering, and ordering items.
defaults
search = ''
(string): initial value of the<CommandInput>
selected = 0
(number): index of initially selected itemopen = false
(boolean): if rendered as a dialog, initially open or notitems = []
(any[]): an array of items that represent subsequent screensordering = true
(boolean): whether to automatically filter and order items
Return Value (commandProps)
items
(any[]): an array of items that represent subsequent screenssearch
(string): value of the inputopen
(boolean): if rendered as a dialog, the open stateselected
(number): index of currently selected itemsetSelected
(function): update currently selected itemlist
(ref): list.current is an array of all visible itemsmap
(ref): map.current is a Map of all items and their associated props