All docs
V21.1
21.2
21.1
20.2
20.1
19.2
The page you are viewing does not exist in version 19.2. This link will take you to the root page.
19.1
The page you are viewing does not exist in version 19.1. This link will take you to the root page.
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.

Custom Shapes

The Diagram UI component provides a collection of built-in shapes. Use the customShapes property to extend this collection with custom shapes.

The toolbox property allows you to add the custom shapes to the toolbox.

A custom shape can be created based on a default shape type or with a custom background image. The type property identifies custom shapes and should be unique.

Shapes with Base Type

Shapes with Base Type

Use the baseType property to specify a base type for a shape. The built-in shape types are shown in the Shape Types section.

View Demo

Diagram control custom shapes

jQuery
index.js
var diagram = $("#diagram").dxDiagram({
    customShapes: employees.map(
        function(emp) {
            return {
                category: "employees",
                type: "employee" + emp.ID,
                baseType: "rectangle",
                defaultText: emp.Full_Name,
                allowEditText: false
            }
        }
    ),
    toolbox: {
        groups: [{ category: "employees", title: "Employees", displayMode: "texts" }]
    }
}).dxDiagram("instance");
Angular
app.component.html
<dx-diagram #diagram id="diagram">
    <dxi-custom-shape *ngFor="let emp of employees"
        category="employees"
        [type]='"employee" + emp.ID'
        baseType="rectangle"
        [defaultText]="emp.Full_Name"
        [allowEditText]="false">
    </dxi-custom-shape>
    <dxo-toolbox>
        <dxi-group category="employees" title="Employees" displayMode="texts"></dxi-group>
    </dxo-toolbox>
</dx-diagram>
Vue
App.vue
<template>
    <DxDiagram
        id="diagram"
        ref="diagram"
    >
        <DxCustomShape
        v-for="employee in employees"
        :category="'employees'"
        :type="'employee' + employee.ID"
        :base-type="'rectangle'"
        :default-text="employee.Full_Name"
        :allow-edit-text="false"
        :key="employee.ID"
        />
        <DxToolbox :visible="true">
            <DxGroup
                :category="'employees'"
                :title="'Employees'"
                :display-mode="'texts'"
            />
        </DxToolbox>
    </DxDiagram>
</template>
<script>
/ ...
data() {
    return {
    employees: service.getEmployees()
    };
},
</script>
React
App.js
class App extends React.Component {
// ...
    render() {
        return (
            <Diagram id="diagram" ref={this.diagramRef}>
                {this.employees.map(function(employee, index) {
                    return <CustomShape category="employees" type={`employee${employee.ID}`} baseType="rectangle"
                        defaultText={employee.Full_Name} allowEditText={false} key={index} />;
                })}
                <Toolbox>
                    <Group category="employees" title="Employees" displayMode="texts" />
                </Toolbox>
            </Diagram>
        );
    }
}

You can use the style and textStyle properties to specify the default style settings for a shape and a shape’s text.

jQuery
index.js
var diagram = $("#diagram").dxDiagram({
    defaultItemProperties: {
        style: "fill: yellow;",
        textStyle: "font-size: 14pt;"
    },
    // ...
}).dxDiagram("instance");
Angular
app.component.html
<dx-diagram #diagram id="diagram">
    <dxo-default-item-properties
        style="fill: yellow;"
        textStyle="font-size: 14pt;">
    </dxo-default-item-properties>
    <!-- ... -->
</dx-diagram>
Vue
App.vue
<DxDiagram
    id="diagram"
    ref="diagram"
>
    <DxDefaultItemProperties
        :style="'fill: yellow;'"
        :textStyle="'font-size: 14pt;'"
    />
    <!-- ... -->
</DxDiagram>
React
App.js
class App extends React.Component {
// ...
    render() {
        return (
            <Diagram id="diagram" ref={this.diagramRef}>
                <DefaultItemProperties style="fill: yellow;" textStyle="font-size: 14pt;"/>
                <!-- ... -->
            </Diagram>
        );
    }
}

Diagram custom shape styles

Shapes with Custom Background Images

Use the backgroundImageUrl property to specify the custom shape's background image in SVG format.

View Demo

roundedRectangle.svg
<svg xmlns="http://www.w3.org/2000/svg" x="0px" y="0px" viewBox="0 0 48 26">
<g><rect rx="5" ry="5" x="0.5" y="0.5" width="47" height="25" 
    style="fill:#FFFFFF;stroke:#000000;stroke-width:1px;"/></g>
</svg>
jQuery
index.js
var diagram = $("#diagram").dxDiagram({
    customShapes: [{
        type: "Rounded Rectangle",
        backgroundImageUrl: "images/shapes/roundedRectangle.svg"
    }],
}).dxDiagram("instance");
Angular
app.component.html
<dx-diagram #diagram id="diagram">
    <dxi-custom-shape 
        type="Rounded Rectangle"
        backgroundImageUrl="images/shapes/roundedRectangle.svg"
    </dxi-custom-shape>
</dx-diagram>
Vue
App.vue
<DxDiagram
    id="diagram"
    ref="diagram"
>
    <DxCustomShape
        :type="'Rounded Rectangle'"
        :background-image-url="'images/shapes/roundedRectangle.svg'"
    >
    </DxCustomShape>
</DxDiagram>
React
App.js
<Diagram id="diagram" ref={this.diagramRef}>
    <CustomShape
        type="Rounded Rectangle"
        backgroundImageUrl="images/shapes/roundedRectangle.svg">
    </CustomShape>
</Diagram>

The image below shows the result:

Custom Shape Background Image

The following properties allow you to customize the image size and position:

Shape Size

Use the following properties to specify the shape size settings:

jQuery
index.js
var diagram = $("#diagram").dxDiagram({
    customShapes: [{
        // ...
        defaultWidth: 2,
        defaultHeight: 1,
    }],
}).dxDiagram("instance");
Angular
app.component.html
<dx-diagram #diagram id="diagram">
    <dxi-custom-shape 
        <!-- ... -->
        [defaultWidth]="2"
        [defaultHeight]="1"
    </dxi-custom-shape>
</dx-diagram>
Vue
App.vue
<DxDiagram
    id="diagram"
    ref="diagram"
>
    <DxCustomShape
        <!-- ... -->
        :default-width="2"
        :default-height="1"
    >
    </DxCustomShape>
</DxDiagram>
React
App.js
<Diagram id="diagram" ref={this.diagramRef}>
    <CustomShape
        // ...
        defaultWidth={2}
        defaultHeight={1}>
    </CustomShape>
</Diagram>

The image below shows the result:

Custom Shape Size

Shape Inner Image

A custom shape can display an inner image. Use the defaultImageUrl property to specify the image URL.

The following properties allow you to specify the image size and position:

jQuery
index.js
var diagram = $("#diagram").dxDiagram({
    customShapes: [{
        // ...
        defaultImageUrl: "images/photo.png",
        imageHeight: 0.8,
        imageWidth: 0.3,
        imageTop: 0.1,
        imageLeft: 0.1,
    }],
}).dxDiagram("instance");
Angular
app.component.html
<dx-diagram #diagram id="diagram">
    <dxi-custom-shape 
        <!-- ... -->
        defaultImageUrl="images/photo.png"
        [imageHeight]="0.8"
        [imageWidth]="0.3"
        [imageTop]="0.1"
        [imageLeft]="0.1"
    </dxi-custom-shape>
</dx-diagram>
Vue
App.vue
<DxDiagram
    id="diagram"
    ref="diagram"
>
    <DxCustomShape
        <!-- ... -->
        :default-image-url="'images/photo.png'"
        :image-height="0.8"
        :image-width="0.3"
        :image-top="0.1"
        :image-left="0.1"
    >
    </DxCustomShape>
</DxDiagram>
React
App.js
<Diagram id="diagram" ref={this.diagramRef}>
    <CustomShape
        // ...
        defaultImageUrl="images/photo.png"
        imageHeight={0.8}
        imageWidth={0.3}
        imageTop={0.1}
        imageLeft={0.1}>
    </CustomShape>
</Diagram>

The image below shows the result:

Custom Shape Inner Image

If the allowEditImage property is set to true, the Diagram context menu displays commands that allow users to change the image.

Custom Shape Image Context Menu

Shape Text

The defaultText property specifies the shape text. Users can change the text if the allowEditText property is set to true.

Use the following properties to specify the size and position of the text container:

jQuery
index.js
var diagram = $("#diagram").dxDiagram({
    customShapes: [{
        // ...
        defaultText: "Employee",
        textLeft: 0.4,
        textWidth: 0.6
    }],
}).dxDiagram("instance");
Angular
app.component.html
<dx-diagram #diagram id="diagram">
    <dxi-custom-shape 
        <!-- ... -->
        defaultText="Employee"
        [textLeft]="0.4"
        [textWidth]="0.6">
    </dxi-custom-shape>
</dx-diagram>
Vue
App.vue
<DxDiagram
    id="diagram"
    ref="diagram"
>
    <DxCustomShape
        <!-- ... -->
        :default-text="'Employee'"
        :text-left="0.4"
        :text-width="0.6"
    >
    </DxCustomShape>
</DxDiagram>
React
App.js
<Diagram id="diagram" ref={this.diagramRef}>
    <CustomShape
        // ...
        defaultText="Employee"
        textLeft={0.4}
        textWidth={0.6}>
    </CustomShape>
</Diagram>

The image below shows the result:

Custom Shape Text

You can use the textStyle property to specify the default style settings for a shape's text.

jQuery
index.js
var diagram = $("#diagram").dxDiagram({
    defaultItemProperties: {
        textStyle: "font-size: 14pt;"
    },
    // ...
}).dxDiagram("instance");
Angular
app.component.html
<dx-diagram #diagram id="diagram">
    <dxo-default-item-properties
        textStyle="font-size: 14pt;">
    </dxo-default-item-properties>
    <!-- ... -->
</dx-diagram>
Vue
App.vue
<DxDiagram
    id="diagram"
    ref="diagram"
>
    <DxDefaultItemProperties
        :textStyle="'font-size: 14pt;'"
    />
    <!-- ... -->
</DxDiagram>
React
App.js
class App extends React.Component {
// ...
    render() {
        return (
            <Diagram id="diagram" ref={this.diagramRef}>
                <DefaultItemProperties textStyle="font-size: 14pt;"/>
                <!-- ... -->
            </Diagram>
        );
    }
}

The image below shows the result:

Custom Shape Text Size

Connection Points

Use the connectionPoints property to specify a collection of custom connection points for a shape. If the property is not specified, the shape displays the default connection points.

jQuery
index.js
var diagram = $("#diagram").dxDiagram({
    customShapes: [{
        // ...
        connectionPoints: [
                { x: 0.5, y: 0 },
                { x: 0.5, y: 1 },
        ]
    }],
}).dxDiagram("instance");
Angular
app.component.html
<dx-diagram #diagram id="diagram">
    <dxi-custom-shape 
        <!-- ... -->
        <dxi-connection-point [x]="0.5" [y]="0"></dxi-connection-point>
        <dxi-connection-point [x]="0.5" [y]="1"></dxi-connection-point>
    </dxi-custom-shape>
</dx-diagram>
Vue
App.vue
<DxDiagram
    id="diagram"
    ref="diagram"
>
    <DxCustomShape
        <!-- ... -->
        <DxConnectionPoint
            :x="0.5"
            :y="0"
        />
        <DxConnectionPoint
            :x="0.5"
            :y="1"
        />
    >
    </DxCustomShape>
</DxDiagram>
React
App.js
<Diagram id="diagram" ref={this.diagramRef}>
    <CustomShape
        // ...
        <ConnectionPoint x={0.5} y={0} />
        <ConnectionPoint x={0.5} y={1} />
    </CustomShape>
</Diagram>

The image below shows the result:

Custom Shape Connection Points