Custom property value renderers
Generally, data in Property Grid and Table components is rendered 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 TypeConverter 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 TypeConverter 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 TypeConverter 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: 28 June, 2024