@itwin/unified-selection-react

Copyright © Bentley Systems, Incorporated. All rights reserved. See LICENSE.md for license terms and full copyright notice.

The @itwin/unified-selection-react package provides React APIs for conveniently using the @itwin/unified-selection package in React applications and components.

React context for unified selection

There are two ways to pass data to React components - through props or context. While the former is preferred, the latter also has its uses. One caveat about React contexts is that context provider and context consumer MUST use the exact same context object. This package delivers a unified selection React context exactly for this reason - it allows context providers and consumers, which may come from different packages and have no direct dependency on each other, to share the same selection storage.

Example usage:

1import { createStorage, Selectables, SelectionStorage } from "@itwin/unified-selection";
2import { UnifiedSelectionContextProvider, useUnifiedSelectionContext } from "@itwin/unified-selection-react";
3
4/** A top-level component that creates the selection storage and sets up the context provider for all inner components to use */
5function App() {
6  const [selectionStorage] = useState(() => createStorage());
7  const idCounter = useRef(0);
8  return (
9    <UnifiedSelectionContextProvider storage={selectionStorage}>
10      <button
11        onClick={() =>
12          selectionStorage.addToSelection({
13            imodelKey,
14            source: "my-button",
15            selectables: [{ className: "BisCore.Element", id: `0x${++idCounter.current}` }],
16          })
17        }
18      >
19        Select an element
20      </button>
21      <MyComponent />
22    </UnifiedSelectionContextProvider>
23  );
24}
25
26/** An internal component that takes unified selection storage from context and prints the number of selected elements */
27function MyComponent() {
28  const selectionContext = useUnifiedSelectionContext();
29  if (!selectionContext) {
30    throw new Error("Unified selection context is not available");
31  }
32
33  function getSelectedElementsCount(storage: SelectionStorage) {
34    return Selectables.size(storage.getSelection({ imodelKey }));
35  }
36
37  const [selectedElementsCount, setSelectedElementsCount] = useState(() => getSelectedElementsCount(selectionContext.storage));
38  useEffect(() => {
39    return selectionContext.storage.selectionChangeEvent.addListener(() => {
40      setSelectedElementsCount(getSelectedElementsCount(selectionContext.storage));
41    });
42  }, [selectionContext.storage]);
43  return `Number of selected elements: ${selectedElementsCount}`;
44}

For the above to work, both - context provider and consumer - must use the same dependency of this package (see symptoms here for when they don't do that). One way to ensure this is to have the following set up:

• Context provider should have a direct dependency on this, as well as the @itwin/unified-selection, packages.
• Context consumer should have a peer dependency on this package. This way, the consumer will use the same version of the context as the provider.