@zendeskgarden/react-selection

@zendeskgarden/react-selection

This package contains utilities and components related to selection in the Garden Design System.

Installation

npm install @zendeskgarden/react-selection

# Peer Dependencies - Also Required
npm install react react-dom prop-types styled-components @zendeskgarden/react-theming

Basic Usage

This package contains several selection components that use the render prop (child-as-a-function) design pattern.

This allows the consumer to create accessible, performant interactions against any UI Components. Regardless of whether they are wrapped in a specific higher-order-component or styling.

This API style is very structured and is meant as an abstraction for Garden to be able to provide simple APIs while still allowing the possibility for consumers to eject into a render prop container for any advanced usages.

View the React render prop documentation for a more in-depth example of usage.

import { KeyboardFocusContainer } from '@zendeskgarden/react-components';

<KeyboardFocusContainer>
  {({ getFocusProps, keyboardFocused }) => (
    <button {...getFocusProps()}>
      {keyboardFocused ? 'Keyboard focused!' : 'Not keyboard focused'}
    </button>
  )}
</KeyboardFocusContainer>;

Render Props in Garden

All render prop components within Garden follow this structure:

Their name will end with Container

• SelectionContainer, MenuContainer, etc.

They will render no UI

• The purpose of the render prop container is to manage state and apply props to any DOM elements given to it.

They will accept their render function from both the render prop as well as the children prop

<Container>
    {({ getItemProps() }) => (
        <div {...getItemProps()}>Test</div>
    )}
</Container>

// is the same as

<Container
    render={({ getItemProps() }) => (
        <div {...getItemProps()}>Test</div>
    )}
/>

All containers will support both Uncontrolled and Controlled state management

• Uncontrolled
  • State is managed entirely within the component. "it just works" mode
• Controlled
  • All stateful properties available within a render prop can be controlled with a prop on the container.
  • All state changes are provided to the onStateChange callback to allow the consumer to fully controll the state.
    • This is useful for components that leverage other containers internally.
    • Also useful if you need to control state in Redux or another store.

// Uncontrolled Usage
<Container>
  {({ getTriggerProps, numClicks }) => <button {...getTriggerProps()}>Clicks {numClicks}</button>}
</Container>;

// Controlled Usage
initialState = {
  numClicks: 5
};

<Container numClicks={state.numClicks} onStateChange={newState => setState(newState)}>
  {({ getTriggerProps, numClicks }) => <button {...getTriggerProps()}>Clicks {numClicks}</button>}
</Container>;

All render props will respect Event Composition

• During development it is common to have to apply events and props to the same elements that the render prop is interacting with.
• To help prevent conflicts between the render prop and your own logic, pass all events and attributes through the render prop function.
• All render props will be able to respect any event.preventDefault() calls and overrides you provide.

<Container>
  {({ getTriggerProps, numClicks }) => (
    <button
      {...getTriggerProps({
        onClick: event => {
          /**
           * This onClick event will be called before being passed to
           * the onClick defined within the example container
           */
          alert('clicked');

          /**
           * Possible to not allow the event to continue
           */
          // event.preventDefault();
        },
        autofocus // We want to use HTML5 autofocus
      })}
    >
      Clicks {numClicks}
    </button>
  )}
</Container>