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:

• Property value type is Primitives.InstanceKey. Generally those are navigation type of properties.
• The property is rendered within a unified selection context. See useUnifiedSelectionContext for more details.

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

url

Component: UrlPropertyValueRenderer

Prerequisites:

• Property type is one of StandardTypeNames.URL, StandardTypeNames.String or StandardTypeNames.Text.

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

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

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",
        },
      }],
    }],
  }],
};

Last Updated: 30 November, 2023