Presentation
Presentation packages are part of the iTwin.js library. The packages' responsibility is to help application developers bring non-graphical iModels' data to users, by solving the following problems:
- Format property values according to user's preferences (language, locale, unit system, etc.).
- Calculate display labels for instances of different ECClasses.
- Gather associated data from different areas of an iModel and return it in a way that's easy to present to users.
- Create hierarchies from iModel (and not only) data.
- Provide components to present non-graphical iModel data to users. This includes tree, table, property grid and some other components and their building blocks, including headless components for use with any UI components library.
The packages
Initially, all presentation packages were part of the itwinjs-core repository, releasing in lock-step with the core packages. At some point, some of the packages were moved to this repository, which broke them out of lock-step and allowed them to have their own, much quicker, release cycle. However, the moved packages are still tightly coupled with the ones in core repository. Both - the Presentation packages in itwinjs-core repository and the ones that we moved to this one - are considered legacy packages:
| Package | Description |
|---|---|
@itwin/presentation-common |
Common types and utilities used by other legacy Presentation packages. |
@itwin/presentation-backend |
APIs for querying presentation data directly from iModels on the backend. |
@itwin/presentation-frontend |
APIs for querying presentation data from iModels through the RPC system. |
@itwin/presentation-components |
React components and their building blocks to display presentation data to users. Uses @itwin/presentation-frontend peer dependency to query the data. |
@itwin/presentation-testing |
Utility APIs for testing components based on legacy Presentation APIs. |
@itwin/presentation-opentelemetry |
APIs for making interop between OpenTelemetry and legacy Presentation types easier. |
While the legacy packages are still maintained and contain some APIs that have no replacements, they're gradually being replaced by new generation packages:
| Package | Description | When to use |
|---|---|---|
@itwin/unified-selection |
APIs for maintaining a single source of truth for what's selected in an application. | You want selection to be synchronized between multiple components in your application. |
@itwin/presentation-hierarchies-react |
APIs for building a headless UI for rendering tree components based on data in an iModel. Also contains a set of iTwinUI-based components for rendering the tree. | You're creating a React application and want a tree component. |
@itwin/presentation-hierarchies |
APIs for creating hierarchical data structures. The package doesn't depend on any backend, frontend or UI specific packages, which allows it to be used in both backend and frontend applications, and in case of the latter, it can be used with any UI framework. | You want to create hierarchical data structures for use cases other than displaying them in a React component. |
@itwin/presentation-shared |
Shared APIs used throughout the new generation Presentation packages. Includes some utilities that may be useful for external consumers too. | You need one of the utilities provided by the package. While most of them are used by the above packages, some might be useful when defining your hierarchies, getting instance labels, etc. |
@itwin/presentation-core-interop |
Interop layer between itwinjs-core and new generation Presentation packages. | You're using the above packages within an iTwin.js-based application. |
The new generation packages are designed to be more modular and have less peer dependencies, making them easier to consume.
The below diagram shows the typical dependency structure of a React application or component that uses Presentation packages to create a tree component:
Contribution
If you wish to contribute to this repository, see our Contributing guide.