@itwin/property-grid-react

Copyright © Bentley Systems, Incorporated. All rights reserved.

The @itwin/property-grid-react package provides React components to build a properties widget that shows properties of selected element(s).

!Widget example

Usage

Typically, the package is used with an AppUI based application, but the building blocks may as well be used with any other iTwin.js React app.

In any case, before using any APIs or components delivered with the package, it needs to be initialized:

``tsx
import { PropertyGridManager } from "@itwin/property-grid-react";
import { IModelApp } from "@itwin/core-frontend";

await PropertyGridManager.initialize(IModelApp.localization);
`

In AppUI based applications widgets are typically provided using UiItemsProvider implementations. The @itwin/property-grid-react package delivers createPropertyGrid function that can be used to add the properties widget to UI:

`tsx
import { createPropertyGrid } from "@itwin/property-grid-react";
import { UiItemsManager } from "@itwin/appui-react";

UiItemsManager.register({ id: "property-grid-provider", getWidgets: () => [createPropertyGrid({})] });
`

The above example uses default widget parameters and results in a component similar to the one visible at the top of this README.

Customization is also possible:

`tsx
import {
AddFavoritePropertyContextMenuItem,
AncestorsNavigationControls,
CopyPropertyTextContextMenuItem,
IModelAppUserPreferencesStorage,
RemoveFavoritePropertyContextMenuItem,
ShowHideNullValuesSettingsMenuItem,
} from "@itwin/property-grid-react";
import type { IModelConnection } from "@itwin/core-frontend";

UiItemsManager.register({
id: "property-grid-provider",
getWidgets: () => [
createPropertyGrid(
// supplies props for the PropertyGridComponent
{
// enable auto-expanding all property categories
autoExpandChildCategories: true,

// enable ancestor navigation by supplying a component for that
ancestorsNavigationControls: (props) => ,

// the list populates the context menu shown when a property is right-clicked.
contextMenuItems: [
// allows adding properties to favorites list
(props) => ,
// allows removing properties from favorites list
(props) => ,
// allows copying property values
(props) => ,
],

// the list populates the settings menu
settingsMenuItems: [
// allows hiding properties without values
(props) => ,
],

// supply an optional custom storage for user preferences, e.g. the show/hide null values used above
preferencesStorage: new IModelAppUserPreferencesStorage("my-favorites-namespace"),

// supply the global selection storage that the widget will use to listen to selection
// changes (more details: https://github.com/iTwin/presentation/blob/master/packages/unified-selection/README.md)
selectionStorage: getGlobalSelectionStorage(),

// supply an optional data provider factory method to create a custom property data provider
createDataProvider: (imodel: IModelConnection) => new PresentationPropertyDataProvider({ imodel, ruleset: MY_CUSTOM_RULESET }),

// ... and a number of props of VirtualizedPropertyGridWithDataProvider from @itwin/components-react is also accepted here
},
),
],
});
`

As seen in the above code snippet, createPropertyGrid takes a number of props that allow customizing not only how the widget behaves, but also how it looks.

$3

The widget and its components rely on unified selection system to tell them which element(s) are currently selected and when the selection changes. As of version 1.16, there are two ways to hook into unified selection:

- Supply the selectionStorage prop to components that use the unified selection system. See Basic usage example for how to set up the storage. At the moment the prop is optional and will only be made required in version 2.0; the components fall back to the legacy system described below if it's not provided.

- The legacy SelectionManager from @itwin/presentation-frontend package, accessed through Presentation.selection API.

$3

The package delivers commonly used building blocks:

- context and setting menu items
- ancestor navigation controls
- preferences storage that uses IModelApp.preferences

Consumers are free to use those blocks or replace them with their own.

Multi-element workflow

The property grid is most useful when viewing properties of a single element. When multiple elements are selected, their properties and values get merged together:

!Properties of multi-element selection

Clicking the "Selected Elements" button opens an element list, which lets you pick one specific element from the selection:

!Selected elements list

Selecting a specific element opens properties for it specifically:

!Properties of a single element from elements list

Ancestor navigation

When ancestorsNavigationControls prop is provided, the widget allows navigating up/down the elements' hierarchy (though bis.ElementOwnsChildElements relationship):

!Ancestor navigation

Note that ancestor navigation is only rendered when there's only one element selected and it has a parent.

Context menu

When the user right clicks on a specific property, a context menu is displayed if at least one context menu item is provided through contextMenuItems prop:

!Context menu

$3

The package delivers two context menu item components for adding properties to and removing them from favorite properties list: AddFavoritePropertyContextMenuItem and RemoveFavoritePropertyContextMenuItem. When selected element contains at least one favorite property, a new "Favorite" category is rendered at the top:

!Favorite properties

Opening context menu for such properties now renders "Remove from Favorite" instead of "Add to Favorite":

!Remove favorite property

$3

The package delivers CopyPropertyTextContextMenuItem component that allows copying selected property value to clipboard.

$3

Adding a custom context menu item can be done as follows:

Define a menu item component:

`tsx
import { PropertyGridContextMenuItem } from "@itwin/property-grid-react";
import type { ContextMenuItemProps } from "@itwin/property-grid-react";

function ExampleContextMenuItem(props: ContextMenuItemProps) {
return (
// render using PropertyGridContextMenuItem to get consistent style
id="example"
title="example"
onSelect={async () => {
// access selected property using props.record.property
}}
>
Click me!

);
}
`

Provide it to the widget:

`tsx
import { PropertyGridComponent } from "@itwin/property-grid-react";

function MyPropertyGrid() {
return ]} />;
}
`

Result:

!Custom context menu item

Settings menu

The settings menu is an entry point for various settings that apply to the widget. It can be accessed by clicking on the three dots button on the right:

!Widget settings menu

The entry point is only rendered if there's at least one settings menu item provided through the settingsMenuItems prop.

$3

The package delivers ShowHideNullValuesSettingsMenuItem that allows users to hide / show properties that don't have values:

| Empty values displayed | Empty values hidden |
| ----------------------------------------------------------------- | ------------------------------------------------------------- |
| !Empty values displayed | !Empty values hidden |

$3

Adding a custom settings menu item can be done as follows:

Define a menu item component:

`tsx
import { PropertyGridSettingsMenuItem } from "@itwin/property-grid-react";

function ExampleSettingsMenuItem() {
return (
// render using PropertyGridSettingsMenuItem to get consistent style
id="example"
onClick={() => {
// handle settings item clicked
}}
>
Click me!

);
}
`

Provide it to the widget:

`tsx
import { PropertyGridComponent } from "@itwin/property-grid-react";

function MyPropertyGrid() {
return ]} />;
}
`

Result:

!Custom settings menu item

Property filtering

Property grid allows its users to filter out properties of an element based on text input.

When an item is selected, click the magnifying glass button and notice the search bar expand.

| Search bar closed | Search bar opened |
| ---------------------------------------- | ----------------------------------------------------- |
| !Search bar closed | !Search bar opened |

One can type into the search bar and notice how properties are automatically filtered based on the search bar input:

!Widget search bar expanded

Note that when the search bar is closed, the filter is discarded and all properties are visible again.

Telemetry

$3

Components from this package allows consumers to track performance of specific features.

This can be achieved by passing onPerformanceMeasured function to PropertyGridComponent or createPropertyGrid. The function is invoked with feature id and time elapsed as the component is being used. List of tracked features:

- "properties-load" - time it takes to load properties data after selection changes.
- "elements-list-load" - time it takes to populate elements list when multiple elements are selected.

$3

Components from this package allows consumers to track the usage of specific features.

This can be achieved by passing onFeatureUsed function to PropertyGridComponent or createPropertyGrid. The function is invoked with feature id and as the component is being used. List of tracked features:

- "single-element" - when properties of a single element are shown.
- "multiple-elements" - when merged properties of multiple elements are shown.
- "elements-list" - when element list is shown.
- "single-element-from-list" - when properties are shown for a single element selected from the element list.
- "ancestor-navigation" - when elements' hierarchy is traversed using ancestor navigation buttons.
- "context-menu" - when context menu for a property is opened.
- "hide-empty-values-enabled" - when property values are loaded with "hide empty values" setting enabled.
- "hide-empty-values-disabled" - when property values are loaded with "hide empty values" setting disabled.
- "filter-properties" - when properties are filtered or selection changes while a filter is applied.

$3

`tsx
import { PropertyGridComponent } from "@itwin/property-grid-react";

function MyPropertyGrid() {
return (
onPerformanceMeasured={(feature, elapsedTime) => {
// user-defined function to handle performance logging.
logPerformance(feature, elapsedTime);
}}
onFeatureUsed={(feature) => {
// user-defined function to handle usage logging.
logUsage(feature);
}}
/>
);
}
`

To track performance or usage of individual components when using them directly, rather than through createPropertyGrid, the onPerformanceMeasured or onFeatureUsed callback should be supplied through TelemetryContextProvider:

`tsx
import { PropertyGrid, TelemetryContextProvider } from "@itwin/property-grid-react";

function ExampleComponent() {
return (
onPerformanceMeasured={(feature, elapsedTime) => {
// user-defined function to handle performance logging.
logPerformance(feature, elapsedTime);
}}
onFeatureUsed={(feature) => {
// user-defined function to handle usage logging.
logUsage(feature);
}}
>


);
}
``