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:
Container
Their name will end with -
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.
render
prop as well as the children
prop
They will accept their render function from both the <Container>
{({ getItemProps() }) => (
<div {...getItemProps()}>Test</div>
)}
</Container>
// is the same as
<Container
render={({ getItemProps() }) => (
<div {...getItemProps()}>Test</div>
)}
/>
Uncontrolled
and Controlled
state management
All containers will support both -
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>