Custom property value renderers

Data in PropertyGrid and Table components is displayed by property value renderers. By defining and registering custom renderers, users can extend property rendering system to support new data types and UI interactions.

A custom renderer can be used by assigning it to specific properties through a property override. See PropertySpecification.renderer section for an example.

Built-in renderers

iTwin.js UI and presentation packages register some built-in value renderers that can be used out of the box.

SelectableInstance

Component: InstanceKeyValueRenderer

Prerequisites:

The renderer renders nothing when property value is undefined. When it's defined, the value is rendered as a clickable text.

The property display value is used for the displayed text. If it is not set, then the Type Converter system is used to calculate displayed string from the raw property value.

When the clickable text clicked on, the available unified selection context is used to replace active selection with the instance key stored in the value by calling UnifiedSelectionContext.replaceSelection.

Default rendering SelectableInstance rendering
Default navigation property value rendering Selectable instance property value rendering

url

Component: UrlPropertyValueRenderer

Prerequisites:

Default for: Properties with StandardTypeNames.URL type name. Generally those are properties with "URI" extended type in ECSchema.

The renderer renders nothing when property value is undefined. When it's defined, the value is rendered as a clickable text.

The property value is passed through the Type Converter system to calculate displayed string. When the text clicked on, the user is navigated to the URL set to that text. Note: the renderer doesn't validate the text to really be a URL.

Default rendering url rendering
Default url property value rendering Url property value rendering

multiline

Component: MultilineTextPropertyValueRenderer

Prerequisites:

  • Property value is of primitive type.

The renderer renders nothing when property value is undefined. When it's defined, the value is passed through the Type Converter system to calculate displayed string. The string is rendered in a single line with ellipsis and is allowed to be expanded into multiple lines to fit the whole string.

Default rendering multiline rendering
Default string property value rendering Multiline collapsed property value rendering Multiline expanded property value rendering

Adding a custom renderer

A new custom property value renderer can be added by registering a class implementing IPropertyValueRenderer to the PropertyValueRendererManager:

// The custom renderer renders the property value in red
PropertyValueRendererManager.defaultManager.registerRenderer("my-renderer", {
  canRender: () => true,
  render: function myRenderer(record: PropertyRecord, ctx?: PropertyValueRendererContext) {
    const defaultRenderer = new PrimitivePropertyValueRenderer();
    return defaultRenderer.render(record, { ...ctx, style: { ...ctx?.style, color: "red" } });
  },
});

The renderer registered above is used whenever a property with that renderer name is being rendered. The below ruleset demonstrates assigning the renderer to a property:

// There's a content rule for returning content of given `bis.Subject` instance. In addition,
// it assigns the `CodeValue` property a custom "my-renderer" renderer.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "Content",
    specifications: [{
      specType: "SelectedNodeInstances",
      propertyOverrides: [{
        name: "CodeValue",
        renderer: {
          rendererName: "my-renderer",
        },
      }],
    }],
  }],
};

Using a custom property value renderer

Last Updated: 30 November, 2023