How to create a Custom Web Control (CWC) for WinCC Unified & V8: step-by-step guide, by hand or with AI

A Custom Web Control, CWC for short, is a made-to-measure screen object built with web technology (HTML, CSS and JavaScript). You place it on a WinCC Unified screen like any button or field, but you decide how it looks and behaves: a production chart, a special table, a panel with several indicators…

Our example is a pie chart with a hole in the middle that shows the total, and three segments for the amounts A, B and C. When an amount changes, its segment grows or shrinks.

The control receives each value through a property: a named input such as ValueA. In TIA Portal you will connect that property to an HMI tag, which is where the project stores the value. The control does not care where the value comes from: in this test you type it on the screen; on a real machine it would come from a PLC.

• Use a CWC when you need a visualization or interaction that the standard WinCC Unified objects do not provide.
• If you only want a symbol to change color or a tank to show its level, start with a dynamic SVG: it has fewer parts.

Siemens · Programming Custom Web ControlsSiemens · Custom Web Controls in WinCC V8

You will work in two places: a text editor to prepare the control and TIA Portal to place it on a screen. The starting files already contain a complete, working chart, so you do not have to write code: just understand each part and make a first change.

Before you start, turn on file name extensions in Windows (File Explorer → View → Show → File name extensions). That way you can see whether a file really ends in .zip or .json and avoid the most common mistake: names like file.zip.zip.

• You need TIA Portal with WinCC Unified (the steps are shown in V21.1) and its simulation or Unified PC Runtime. Runtime is the program that runs the HMI screen.
• Use a text editor such as Visual Studio Code and Windows File Explorer, which can already create ZIP files. You do not need a PLC.

1. 1

   Where · TIA Portal → project tree → HMI device → Screens

   Prepare an empty screen

   Open or create a test project with a WinCC Unified device (for example, Unified PC). Inside the device, under Screens, create a screen called TestCWC and save the project. Note where its folder is: by default, TIA Portal creates it in Documents\Automation\<ProjectName>.

   ✓

   Check: You have an empty screen and know which folder on your PC holds the project.

2. 2

   Where · Windows File Explorer

   Download and extract the starting files

   Download the pie chart with the button in this section: it is a ZIP called {8D821B43-4EF5-4BF1-A31D-931D283C7C04}.zip. Keep an untouched copy. Right-click → Extract All and, in the dialog, change the destination folder name to HmixPieChart (Windows suggests the long GUID name).

   ✓

   Check: Inside HmixPieChart you see manifest.json and the folders assets and control.

3. 3

   Where · Visual Studio Code or your text editor

   Open the folder in your editor

   In Visual Studio Code, choose File → Open Folder and select HmixPieChart. If you do not see the file tree, open the Explorer panel (Ctrl+Shift+E). You will open each file from there in the next section.

   ✓

   Check: You see the control's file tree in the editor side bar.

Siemens · Installing and using CWCs

A CWC is a handful of text files. You do not need to memorize them, just know what each one does. manifest.json introduces the control to TIA Portal, index.html contains what you see and code.js decides how the chart changes when a value arrives.

1. 1

   Where · Editor → Explorer panel of HmixPieChart

   Check where each file goes

   The top level holds manifest.json and the folders assets and control. Inside control are index.html, code.js and webcc.min.js. The last one is Siemens' official library that connects the control with WinCC Unified: it is already included and you must not modify it. assets keeps its license and, in your own controls, can hold the icon.

   One folder, three parts working together

   • HmixPieChart/
     • manifest.json

       The control's ID card: its name, its identifier (GUID) and the values it can receive from WinCC Unified.

     • assets/
       • SIEMENS-LICENSE.md

         The license that comes with Siemens' communication library.

     • control/
       • index.html

         The page that draws the chart. Its look is here too: colors, sizes and layout.

       • code.js

         The instructions that update the chart when a value changes.

       • webcc.min.js

         The communication bridge with WinCC Unified. It is Siemens' official file: do not edit it.

   ✓

   Check: Your folder has the same structure as the diagram, with no files out of place.

2. 2

   Where · Editor → manifest.json

   Recognize the chart's three inputs

   Open manifest.json and look for properties. You will see ValueA, ValueB and ValueC. Each one states "type": "number" (it receives a number) and an initial value in default: 45, 35 and 20. These are the three properties that will appear in TIA Portal. Further up, under identity, you will also find displayname (the name TIA Portal shows, HMIx Pie Chart) and type, with the control's unique identifier. Do not change anything in this file during the first test.

   ✓

   Check: You know which three amounts the control receives, what they are called and where its identifier is.

3. 3

   Where · Editor → control/index.html

   Make your first visible change

   This file uses HTML to organize the content and, inside the <style> tag, CSS rules that define colors and sizes. Search (Ctrl+F) for the text PIE CHART and replace it with PRODUCTION. Change only those letters, not the <span> tags around them, and save the file (Ctrl+S).

   ✓

   Check: The chart header says PRODUCTION: you have customized your control with an easy-to-check change.

4. 4

   Where · Editor → control/code.js

   Identify the part that updates the values

   code.js is written in JavaScript, the language that describes the control's actions. Look for drawChart: that function calculates the total and draws the segments. Further down, WebCC.start connects to WinCC Unified and onPropertyChanged reports every time a property changes. Notice that ValueA, ValueB and ValueC are spelled exactly as in the manifest. You do not need to touch anything here.

   ✓

   Check: You can tell the appearance (index.html) from the logic that receives and draws the data (code.js).

5. 5

   Where · Windows Explorer → HmixPieChart → control

   Check the design before packaging

   Double-click index.html to open it in your browser. You should see the PRODUCTION header and the chart with 45, 35 and 20. It is normal that it does not react to anything: outside WinCC the control has no tags and shows its initial values. If you still see PIE CHART, save the change in the editor and reload the page (F5).

   ✓

   Check: The chart is drawn and shows the text you just changed.

6. 6

   Where · Windows Explorer → inside HmixPieChart

   Create the ZIP that TIA Portal will import

   Go into HmixPieChart and select manifest.json, assets and control together (Ctrl+click). Right-click → Compress to ZIP file (on Windows 10: Send to → Compressed (zipped) folder). Select those three items, not the HmixPieChart folder. Rename the resulting ZIP exactly {8D821B43-4EF5-4BF1-A31D-931D283C7C04}.zip, braces included: it is the GUID in the manifest's identity → type. If the name differs, TIA Portal will not show the control.

   From the working folder to the TIA Portal project

   1. 1

      Select the folder's contents

      ✓manifest.json

      ✓assets/

      ✓control/

      Go into HmixPieChart and select these three items. The HmixPieChart folder itself does not go into the ZIP.

   2. 2

      Compress and name the ZIP with the GUID

      {8D821B43-4EF5-4BF1-A31D-931D283C7C04}.zip

      The ZIP name matches the GUID in manifest.json. The braces are part of the name.

   3. 3

      Copy the whole ZIP to this location

      • Your project/
        • UserFiles/
          • CustomControls/
            • {8D821B43-4EF5-4BF1-A31D-931D283C7C04}.zip

      The ZIP goes here, still compressed. Create UserFiles and CustomControls if they do not exist.

   ✓

   Check: When you open the ZIP you see manifest.json, assets and control directly, and its name matches the GUID.

To follow this guide, keep the example's identity. When you create a separate control, generate a new GUID (for example in PowerShell with [guid]::NewGuid()), write it in upper case in identity → type (guid://…) and use the same GUID, in braces, as the ZIP name. Renaming only the ZIP does not change the identity.

{
  "mver": "1.2.0",
  "control": {
    "identity": {
      "name": "HmixPieChart",
      "version": "1.0",
      "displayname": "HMIx Pie Chart",
      "type": "guid://8D821B43-4EF5-4BF1-A31D-931D283C7C04",
      "start": "./control/index.html"
    },
    "metadata": {
      "author": "HMIx",
      "description": "Educational read-only three-value pie chart"
    },
    "contracts": {
      "api": {
        "methods": {},
        "events": {},
        "properties": {
          "ValueA": { "type": "number", "default": 45 },
          "ValueB": { "type": "number", "default": 35 },
          "ValueC": { "type": "number", "default": 20 }
        }
      }
    },
    "types": {}
  }
}

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>HMIx Pie Chart</title>
    <style>
      * {
        box-sizing: border-box;
      }
      body {
        margin: 0;
        padding: 20px;
        background: #171e26;
        color: #f3f5f6;
        font:
          14px system-ui,
          sans-serif;
      }
      header {
        display: flex;
        justify-content: space-between;
        color: #bac5ce;
        font-size: 11px;
        letter-spacing: 0.14em;
      }
      main {
        display: flex;
        align-items: center;
        justify-content: center;
        gap: 24px;
        min-height: 240px;
      }
      svg {
        width: 55%;
        max-width: 300px;
        flex-shrink: 0;
      }
      ul {
        list-style: none;
        padding: 0;
        min-width: 110px;
      }
      li {
        display: grid;
        grid-template-columns: 10px 1fr auto;
        align-items: center;
        gap: 10px;
        padding: 14px 0;
        border-bottom: 1px solid #35404a;
      }
      .dot {
        width: 8px;
        height: 8px;
        border-radius: 50%;
      }
      small {
        display: block;
        margin-top: 4px;
        color: #bac5ce;
        font-variant-numeric: tabular-nums;
      }
      strong {
        font-variant-numeric: tabular-nums;
      }
      @media (max-width: 360px) {
        body {
          padding: 12px;
        }
        main {
          gap: 12px;
        }
      }
    </style>
  </head>
  <body>
    <header><span>HMIx</span><span>PIE CHART</span></header>
    <main>
      <svg viewBox="0 0 220 220" role="img" aria-labelledby="chart-title">
        <title id="chart-title">Distribution of A, B and C</title>
        <circle
          cx="110"
          cy="110"
          r="76"
          fill="none"
          stroke="#35404a"
          stroke-width="28"
        />
        <g transform="rotate(-90 110 110)" fill="none" stroke-width="28">
          <circle id="ValueA" cx="110" cy="110" r="76" stroke="#47d2c8" />
          <circle id="ValueB" cx="110" cy="110" r="76" stroke="#79a9ed" />
          <circle id="ValueC" cx="110" cy="110" r="76" stroke="#f5c16c" />
        </g>
        <text
          id="total"
          x="110"
          y="115"
          text-anchor="middle"
          fill="#f3f5f6"
          font-size="30"
          font-weight="600"
        >
          100
        </text>
        <text
          x="110"
          y="139"
          text-anchor="middle"
          fill="#bac5ce"
          font-size="10"
          letter-spacing="2"
        >
          A + B + C
        </text>
      </svg>
      <ul aria-label="Values and shares">
        <li>
          <i class="dot" style="background: #47d2c8"></i
          ><span>A<small id="ValueA-amount">45</small></span
          ><strong id="ValueA-percent">45%</strong>
        </li>
        <li>
          <i class="dot" style="background: #79a9ed"></i
          ><span>B<small id="ValueB-amount">35</small></span
          ><strong id="ValueB-percent">35%</strong>
        </li>
        <li>
          <i class="dot" style="background: #f5c16c"></i
          ><span>C<small id="ValueC-amount">20</small></span
          ><strong id="ValueC-percent">20%</strong>
        </li>
      </ul>
    </main>
    <script src="webcc.min.js"></script>
    <script src="code.js"></script>
  </body>
</html>

/* HMIx educational pie chart. Values are amounts, not required percentages. */
var values = { ValueA: 45, ValueB: 35, ValueC: 20 };
var keys = ['ValueA', 'ValueB', 'ValueC'];
var circumference = 2 * Math.PI * 76;

function drawChart() {
  // Normalize before adding to avoid overflow for very large finite values.
  var maximum = Math.max(values.ValueA, values.ValueB, values.ValueC, 1);
  var sum = keys.reduce(function (n, key) {
    return n + values[key] / maximum;
  }, 0);
  var offset = 0;
  keys.forEach(function (key) {
    var fraction = sum ? values[key] / maximum / sum : 0;
    var arc = document.getElementById(key);
    var length = fraction * circumference;
    arc.setAttribute('stroke-dasharray', length + ' ' + circumference);
    arc.setAttribute('stroke-dashoffset', String(-offset));
    arc.setAttribute('visibility', fraction ? 'visible' : 'hidden');
    document.getElementById(key + '-amount').textContent = String(values[key]);
    document.getElementById(key + '-percent').textContent =
      Math.round(fraction * 100) + '%';
    offset += length;
  });
  var total = values.ValueA + values.ValueB + values.ValueC;
  document.getElementById('total').textContent = isFinite(total)
    ? String(total)
    : '—';
}

function setValue(key, value) {
  if (keys.indexOf(key) === -1 || typeof value !== 'number' || !isFinite(value))
    return;
  values[key] = Math.max(0, value);
}

drawChart();
if (typeof WebCC !== 'undefined') {
  WebCC.start(
    function (connected) {
      if (!connected) return;
      keys.forEach(function (key) {
        setValue(key, WebCC.Properties[key]);
      });
      drawChart();
      WebCC.onPropertyChanged.subscribe(function (change) {
        setValue(change.key, change.value);
        drawChart();
      });
    },
    {
      methods: {},
      events: [],
      properties: { ValueA: 45, ValueB: 35, ValueC: 20 },
    },
    ['HMI'],
    10000,
  );
}

Siemens · Manifest structureSiemens · WebCC and the Runtime interfaceSiemens · Example files and WebCC librarySiemens · Creating the ZIP file

The package is ready. Now you move from the text editor to TIA Portal. The ZIP goes inside the project folder, in a specific subfolder, so that TIA Portal can find it.

1. 1

   Where · Windows Explorer → your TIA project folder

   Copy the ZIP to its destination folder

   Open the project folder you noted at the start and go into UserFiles (create it if it does not exist). Inside, create a folder called CustomControls if it does not exist and copy the ZIP there. Leave it compressed: do not extract it and do not copy only index.html.

   ✓

   Check: The path ends in UserFiles\CustomControls\{8D821B43-4EF5-4BF1-A31D-931D283C7C04}.zip.

2. 2

   Where · TIA Portal → TestCWC screen → Tools task card

   Make TIA Portal find it

   Open the TestCWC screen. In the Tools task card on the right, expand the My controls pane and click its Update button.

   ✓

   Check: HMIx Pie Chart appears in the My controls pane.

3. 3

   Where · TIA Portal → My controls → TestCWC screen

   Place it on the screen

   Drag HMIx Pie Chart from the pane onto the screen. Give it a size of roughly 480 × 300 pixels and leave room on one side for the three numeric fields you will add later.

   ✓

   Check: The screen contains an instance of your chart with the PRODUCTION header.

4. 4

   Where · Selected control → Inspector window → Properties → Properties → Interface

   Find the inputs you prepared

   Select the control and, in the Inspector window, open Properties → Properties → Interface. There you find ValueA, ValueB and ValueC with their initial values 45, 35 and 20. In the next section you will replace those fixed values with tags.

   

   ✓

   Check: You see the same three properties that manifest.json defined.

Siemens · Installing and using CWCs

The control has three inputs; now you will feed them data. You will create three internal tags (they live inside the HMI, no PLC) and three I/O fields. An I/O (input/output) field is a box on the screen where you can read and write a number. Each box and its chart segment will share the same tag.

1. 1

   Where · TIA Portal → HMI device → HMI tags → tag table

   Create the three test tags

   Open the default tag table and add ProductionA, ProductionB and ProductionC. In the Connection column choose Internal tag and pick a numeric data type, for example Real.

   ✓

   Check: The table contains three numeric internal tags with those names.

2. 2

   Where · TestCWC screen → selected CWC → Properties → Properties → Interface

   Connect each tag to its input

   In the ValueA row, open the Dynamization column, choose Tag and select ProductionA. “Dynamizing” means the property takes its value from a tag instead of a fixed number. Repeat with ValueB → ProductionB and ValueC → ProductionC. Leave Read only enabled: the chart only displays the data; you will write it from the boxes.

   How the three values travel to the chart

   1. 1

      You type a number in each I/O field

      A

      45

      B

      35

      C

      20

      I/O means input/output: the field shows a value and lets you change it during the test.

   2. 2

      The HMI tag stores that number

      ProductionA

      45

      ProductionB

      35

      ProductionC

      20

      They are internal project tags. You do not need a PLC for this test.

   3. 3

      The control property receives the value

      ValueA

      45

      ValueB

      35

      ValueC

      20

      Bind each property to its tag in the Dynamization column of the Interface.

   4. 4

      The chart redraws

      A: 45% · B: 35% · C: 20%

      With 45, 35 and 20 the sum is 100. If you change a number, all three shares are recalculated.

   

   ✓

   Check: Each chart input receives a different tag, as the diagram shows.

3. 3

   Where · TestCWC screen → Tools → Elements → I/O field

   Add the boxes to type the numbers

   Drag three I/O fields next to the chart. In each one, choose the Input/output mode and connect its Process value to ProductionA, ProductionB and ProductionC respectively. Add the texts A, B and C next to them to tell them apart.

   ✓

   Check: You have the chart and three fields: one for A, one for B and one for C.

4. 4

   Where · TIA Portal → project tree → HMI device

   Compile and open the screen in Runtime

   Right-click TestCWC and choose Define as start screen (you can also set it in Runtime settings → General). Select the HMI device, compile it (right-click → Compile → Software) and fix any errors. Then click Start simulation or download the project to your Unified PC Runtime. The web client opens: log in with a project user. If you have none, create one in Security settings → Users and roles, assign it an HMI role (for example, HMI Administrator) and compile again.

   ✓

   Check: You see the screen running and can type numbers into the I/O fields.

5. 5

   Where · Screen in Runtime → fields A, B and C

   Check the first split and change A

   Type 45 in A, 35 in B and 20 in C, confirming each number with Enter. The total must be 100. Now change only A to 90 and confirm: its segment grows and the total becomes 145. The numbers are amounts, not percentages: the control works out each one's share of the total.

   ✓

   Check: The chart changes as soon as you confirm a number, without reloading the screen.

6. 6

   Where · Screen in Runtime → fields A, B and C

   Also check the empty state

   Enter 0 in all three fields: the colored segments disappear and an empty ring with total 0 remains. Type 45, 35 and 20 again and reload the browser page (F5) to check that the control reads the current values when it opens.

   ✓

   Check: The control shows both normal data and the no-production case.

Siemens · Installing and using CWCsSiemens · Engineering example and original screenshots

• HMIx Pie Chart does not appear in My controls: open the ZIP; its top level must hold manifest.json, assets and control, with no folder in between. Check that it is named exactly {8D821B43-4EF5-4BF1-A31D-931D283C7C04}.zip (with extensions visible, so it is not .zip.zip), that it sits in UserFiles\CustomControls of the open project, and click Update.
• ValueA, ValueB or ValueC is missing: use this guide's ZIP and do not rename anything in manifest.json; names are case-sensitive. The Pie Chart product in the catalog has different properties.
• The chart does not change in Runtime: confirm the number with Enter. Then check that the I/O field is in Input/output mode and that the field and the control property use the same tag.
• You cannot log in to Runtime: the client asks for a project user. Create one in Security settings → Users and roles with an HMI role, compile and download again.
• PIE CHART still appears: save index.html, rebuild the ZIP and replace the one in the project. Click Update in My controls: the Inspector window reports that the object was updated. Compile and download the HMI again. Editing the working folder alone does not change what is already in TIA Portal.
• It works on the PC but fails on a Unified Comfort Panel: make sure every dependency travels inside the ZIP and review Siemens' restrictions for that device, especially external resources and data requests.

Once it works, change one thing at a time: first a text or a color, then another way of showing the data. If you rename a property or change its type, TIA Portal may lose its configuration on existing instances. Always validate the control on the device where it will be used.

Siemens · CWC restrictions on Unified Comfort Panels

You now know what a CWC looks like inside. To create new controls without writing HTML or JavaScript, you can use the HMIx AI generator (ai.hmix.tech): describe the control in plain language and the AI prepares the design, the properties, the manifest.json and the {GUID}.zip package ready for TIA Portal. You can start for free with the Community plan.

What you learned here still applies: importing, connecting tags and testing in Runtime work exactly the same way.

1. 1

   Where · ai.hmix.tech → Custom Web Control

   Describe the control you need

   Write what it should show and which data it receives, for example: “Pie chart with three production amounts A, B and C, total in the center and a legend with percentages”. You can also attach a reference image.

   ✓

   Check: The AI generates a first visual version that you can refine in the chat or the visual editor.

2. 2

   Where · Generator → definition and simulation steps

   Review properties and simulation

   Check the properties the AI proposes (the equivalents of ValueA, ValueB and ValueC) and move them with the simulation controls to see how the control reacts before downloading it.

   ✓

   Check: The control responds in the simulation as you expect.

3. 3

   Where · Generator → generation and installation step

   Download the package

   Download the result. The download ZIP contains the documentation and, inside it, the control's {GUID}.zip package: that inner file is the one you copy, still compressed, to UserFiles\CustomControls.

   ✓

   Check: You have a {GUID}.zip in the same format as this guide's.

4. 4

   Where · TIA Portal → My controls

   Import and test it as here

   Follow “Import the CWC into TIA Portal” and “Connect tags and test in Runtime” using your new control's names.

   ✓

   Check: Your AI-generated control works on your WinCC Unified screen.

On the free plan, generated controls are published in the HMIx catalog so other users can use them too; paid plans let you keep them private.