---
title: "Custom KPI Bar"
slug: "custom-kpi-bar"
category: "Widgets"
reactComponent: "ArcWidgetKpiBar"
reactTier: "mini"
reactSince: "0.1.0-alpha.5"
reactExample: "kpi_bar.tsx"
locale: "es"
hosts: "ninox"
---

# Custom KPI Bar

## AI Defaults (read first)

- **Function name**: `arcKPIBar` (NOT `arcCustomKpiBar`).
- **uniqueId**: Required, `"kpi-" + Nr`.
- **cards**: Array of `{ card: 1, title: "...", value: ... }` – `card` is eine Nummer (1, 2, 3…).
- **Klick (Ninox):** `actions: [...]` auf der Karte — der Adapter setzt intern `clickable: true`. Unterstützte Action-Typen wie bei arcCustomButton.
- **Klick (React):** `clickable: true` auf der Karte; `onClick(event, cardIndex)` am Host (`cardIndex` = 0-basierter Index in `cards`) — **kein** `actions` in `data`.
- **Large numbers**: Use `shortNumbers(value)` for auto-formatting (1.2K, 3.5M).
- **height**: Set in `settings: { height: "250px" }`.
- **Null handling**: Do NOT guard values with `else "" end`, omit the else.

# Custom KPI Bar

![](https://framerusercontent.com/images/8Ouhx7SKhEFXPG22FsEV5i0g.png)

La Custom KPI Bar consiste en un código de aplicación que insertas en un campo de fórmula de Ninox en la interfaz deseada de la base de datos. Este se compone de una parte general (settings), en la que realizas los ajustes básicos, y un área de detalle (cards), en la que determinas de forma individual qué valores, colores o acciones aplicas.

## Código de aplicación completo

Aquí ves un código de aplicación de ejemplo que define tu KPI Bar. Con *data* defines los contenidos que luego haces mostrar con la función *arcKPIBar()*.


```javascript
let data := {
        uniqueId: "KPI Bar 2",
        settings: {
            height: "",
            colorLabel: "",
            fontSizeLabel: "15",
            colorValue: "",
            fontSizeValue: "40px",
            backgroundColor: "",
            borderColor: ""
        },
        cards: [{
                card: 1,
                settings: {
                    colorLabel: "#8e99c4",
                    fontSizeLabel: "15",
                    colorValue: "#8e99c4",
                    fontSizeValue: "40px",
                    backgroundColor: "#49547e",
                    borderColor: "#646f9b"
                },
                title: "Gesamtumsatz",
                value: "€" + shortNumbers(cnt((select Projekte).Umsatz)),
                subtitle: "€" +
                shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
                " in diesem Monat"
            }]
    };
arcKPIBar(data)
```

## Ajustes generales

En los ajustes generales realizas la configuración básica de tu tarjeta KPI. Esto **afecta a todas las tarjetas**. A continuación se explican los distintos parámetros:

*uniqueId* asigna un nombre propio a tu KPI Bar. Es importante que esta denominación sea única. Si, por ejemplo, tienes varias KPI Bars en un registro y no indicas un nombre único, los valores se sobrescriben entre sí. Intenta por tanto denominarlas de la forma más individual posible.


```javascript
uniqueId: "KPI Bar 1",
```

*height* determina la altura de tu KPI Bar. Aquí puedes indicar los siguientes valores:


```javascript
height: "250px" // Pixel Werte
```

*colorLabel* indica el color del texto. Aquí puedes indicar los siguientes valores:


```javascript
colorLabel: "FFFFFF" // HEX Code für deinen Farbwert.
```

*fontSizeLabel* determina el tamaño de tu texto sobre y bajo el valor KPI. Este lo indicas con los siguientes valores:


```javascript
fontSizeLabel: "12px" // Pixel Werte
```

*colorValue* indica el color de tu valor KPI. Aquí puedes indicar los siguientes valores:


```javascript
colorValue: "FFFFFF" // HEX Code für deinen Farbwert.
```

*fontSizeValue* determina el tamaño de tu valor KPI. Este lo indicas con los siguientes valores:


```javascript
fontSizeValue: "35px" // Pixel Werte
```

*backgroundColor* determina el color de fondo de tu tarjeta. Aquí puedes indicar los siguientes valores:


```javascript
backgroundColor: "FFFFFF" // HEX Code für deinen Farbwert.
```

*borderColor* determina el color del borde de la tarjeta. Aquí puedes indicar los siguientes valores:


```javascript
borderColor: "FFFFFF" // HEX Code für deinen Farbwert.
```

## Valores estándar como fallback

💡 **Nota: **Todos los valores de los parámetros se indican entre comillas. Si no introduces nada entre las comillas, el sistema recurre a un fallback. Es decir, hay valores estándar preconfigurados, de forma que siempre se muestre algo. Aquí ves la tarjeta con los valores de fallback:

![](https://framerusercontent.com/images/vgJSRSruJ02ARYRMMMm6yshxB0A.png)

## Área de detalle

En el área de detalle defines todos los estilos y valores de las distintas tarjetas KPI. Es decir: cada tarjeta se puede diseñar de forma individual. En ese caso, los estilos sobrescriben los valores de los ajustes generales. A continuación ves un código de ejemplo para una tarjeta KPI.


```javascript
{card: 1,
        settings: {
            colorLabel: "#F9244B",
            fontSizeLabel: "15",
            colorValue: "#F9244B",
            fontSizeValue: "40px",
            backgroundColor: "#FCD9DF",
            borderColor: "#EABDC5"
            },
        title: "Gesamtumsatz",
        value: "€" + shortNumbers(cnt((select Projekte).Umsatz)),
        subtitle: "€" + shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
                " in diesem Monat"
            }
```

*card* es el número individual de tu tarjeta y aporta claridad y estructura de datos. Lo indicas de la siguiente manera:


```javascript
card: 1 // Nummer deiner Karte als reine Zahl
```

*settings* son los mismos valores de configuración que en los ajustes generales. Aquí puedes sobrescribirlos por tarjeta y diseñarlos de forma individual.


```javascript
settings: {
    colorLabel: "#F9244B",
    fontSizeLabel: "15",
    colorValue: "#F9244B",
    fontSizeValue: "40px",
    backgroundColor: "#FCD9DF",
    borderColor: "#EABDC5"
        }
```

*title* es el encabezado sobre tu valor KPI.


```javascript
title: "Gesamtumsatz" // Reiner, statischer Text als Überschrift
title: if Status=abgeschlossen then "Gesamtumsatz" else "Erwarteter Umsatz" // Du kannst alle normalen Ninox Funktionen verwenden, um dir deinen Titel ausgeben zu lassen.
```

*value* muestra el valor de tu tarjeta KPI.


```javascript
value: "5.000.000€" // Reiner, statischer Text als Wert
value: "€" + shortNumbers(cnt((select Projekte).Umsatz)) // Greife auf Ninox Felder zurück und arbeite mit üblichen Ninox Funktionen / -Schreibweisen.
```

*subtitle* indica el subtítulo bajo tu valor KPI.


```javascript
subtitle: "in diesem Monat" // Reiner, statischer Text als Unterschrift
subtitle: "€" +
                shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
                " in diesem Monat" // Greife auf Ninox Felder zurück und arbeite mit üblichen Ninox Funktionen / -Schreibweisen.
```

*actions* (solo Ninox) define acciones que se ejecutan al hacer clic en la tarjeta KPI. El adapter genera a partir de esto `clickable: true` para el widget core — la tarjeta se vuelve clicable (cursor: pointer, efecto hover). Tipos de action compatibles: `update`, `popup`, `openRecord`, `fullscreen`, `openUrl`, `create`, `delete` (análogo a arcCustomButton).

*clickable* (React / otros hosts) marca la tarjeta como clicable. Establece `clickable: true` en `data` y reacciona en el host a `onClick(event, cardIndex)` — `cardIndex` es el índice **de base cero** en `cards`. En React **no** uses `actions` en `data`.

```javascript
actions: [{
    type: "update",
    recordId: Nr,
    field: fieldId(Nr, "helper_activeTab"),
    value: "umsatz"
}]
actions: [{ type: "popup", recordId: Nr }]
```

## Duplicación de tus tarjetas KPI

Puedes decidir tú mismo cuántas tarjetas KPI quieres mostrar. Mediante copiar y pegar puedes duplicar fácilmente tus tarjetas en el código. Separa las distintas cards con una coma (,).

<pre data-language="JavaScript"><code>cards: [{
    card: 1,
    title: "Gesamtumsatz",
    value: "€" + shortNumbers(cnt((select Projekte).Umsatz)),
    subtitle: "€" +
    shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
    " in diesem Monat"
}, {
    card: 2,
    title: "Abgeschlossen gesamt",
    value: shortNumbers(cnt(select Projekte where Abgeschlossen != null)),
    subtitle: shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
    " in diesem Monat"
}, {
    card: 3,
    title: "Conversion Rate",
    value: round(cnt(select Projekte where Abgeschlossen != null) / cnt(select Projekte) * 100, 2) +
    "%",
    subtitle: round(cnt(select Projekte where Abgeschlossen != null and month(Abgeschlossen) = month(today())) /
    cnt(select Projekte where month(Abgeschlossen) = month(today())) *
    100, 2) + "%" + " in diesem Monat"
}]
    </code></pre>## Parámetros

En el área de detalle de tus tarjetas KPI puedes definir diversos parámetros. Puedes decidir tú mismo qué parámetros quieres definir. Si simplemente omites parámetros, estos no se muestran. Aquí ves todos los parámetros que puedes usar en la KPI Bar:


```javascript
card: "",
    settings: {
        colorLabel: "",
        fontSizeLabel: "",
        colorValue: "",
        fontSizeValue: "",
        backgroundColor: "",
        borderColor: ""
    },
    title: "",
    value: "",
    subtitle: "",
    actions: [{ type: "update", recordId: Nr, field: fieldId(Nr, "Feld"), value: "..." }]
```

## Funciones

Puedes definir tus parámetros con todas las funciones y notaciones de Ninox. Pero también te hemos creado algunas funciones útiles de arcRider que hacen tus valores todavía más claros.

*shortNumbers()* abrevia números largos a partir de 4 cifras y añade el nombre del número (mil, mill., mrd., bill.) tras el valor.


```javascript
shortNumbers("2000") // Gibt den abgekürzten Wert der statischen Zahl aus (2 Tsd.)
shortNumbers(cnt((select Projekte).Umsatz)) // Gibt den abgekürzten Wert der dynamischen Zahl aus (z.B. 35 Mio.)
```

## Ejemplos

A continuación encontrarás algunos ejemplos prácticos que ilustran los distintos usos de la KPI Bar.

### KPI Card Fallback

![](https://framerusercontent.com/images/vgJSRSruJ02ARYRMMMm6yshxB0A.png)


```javascript
let data := {
        uniqueId: "KPI Bar 1",
        settings: {
            height: "",
            colorLabel: "",
            fontSizeLabel: "15",
            colorValue: "",
            fontSizeValue: "40px",
            backgroundColor: "",
            borderColor: ""
        },
        cards: [{
                card: 1,
                title: "Gesamtumsatz",
                value: "€" + shortNumbers(cnt((select Projekte).Umsatz)),
                subtitle: "€" +
                shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
                " in diesem Monat"
            }, {
                card: 2,
                title: "Abgeschlossen gesamt",
                value: shortNumbers(cnt(select Projekte where Abgeschlossen != null)),
                subtitle: shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
                " in diesem Monat"
            }, {
                card: 3,
                title: "Conversion Rate",
                value: round(cnt(select Projekte where Abgeschlossen != null) / cnt(select Projekte) * 100, 2) +
                "%",
                subtitle: round(cnt(select Projekte where Abgeschlossen != null and month(Abgeschlossen) = month(today())) /
                cnt(select Projekte where month(Abgeschlossen) = month(today())) *
                100, 2) +
                "%" +
                " in diesem Monat"
            }]
    };
arcKPIBar(data)
```

### KPI Bar individual

![](https://framerusercontent.com/images/al3UmQQbGCgJyxMk6N7cRKGowRw.png)


```javascript
let data := {
        uniqueId: "KPI Bar 2",
        settings: {
            height: "",
            colorLabel: "",
            fontSizeLabel: "15",
            colorValue: "",
            fontSizeValue: "40px",
            backgroundColor: "",
            borderColor: ""
        },
        cards: [{
                card: 1,
                settings: {
                    colorLabel: "#F9244B",
                    fontSizeLabel: "15",
                    colorValue: "#F9244B",
                    fontSizeValue: "40px",
                    backgroundColor: "#FCD9DF",
                    borderColor: "#EABDC5"
                },
                title: "Gesamtumsatz",
                value: "€" + shortNumbers(cnt((select Projekte).Umsatz)),
                subtitle: "€" +
                shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
                " in diesem Monat"
            }, {
                card: 2,
                settings: {
                    colorLabel: "#000",
                    fontSizeLabel: "15",
                    colorValue: "#1f96bf",
                    fontSizeValue: "40px",
                    backgroundColor: "#FDE8A5",
                    borderColor: "#D9C78C"
                },
                title: "Abgeschlossen gesamt",
                value: shortNumbers(cnt(select Projekte where Abgeschlossen != null)),
                subtitle: shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
                " in diesem Monat"
            }, {
                card: 3,
                settings: {
                    colorLabel: "#CAECCD",
                    fontSizeLabel: "15",
                    colorValue: "#CAECCD",
                    fontSizeValue: "40px",
                    backgroundColor: "#56C275",
                    borderColor: "#9DCDA1"
                },
                title: "Conversion Rate",
                value: round(cnt(select Projekte where Abgeschlossen != null) / cnt(select Projekte) * 100, 2) +
                "%",
                subtitle: cnt(select Projekte where Abgeschlossen != null and month(Abgeschlossen) = month(today())) /
                cnt(select Projekte where month(Abgeschlossen) = month(today())) *
                100 +
                "%" +
                " in diesem Monat"
            }]
    };
arcKPIBar(data)
```

### KPI Bar modo oscuro

![](https://framerusercontent.com/images/8Ouhx7SKhEFXPG22FsEV5i0g.png)


```javascript
let data := {
        uniqueId: "KPI Bar 3",
        settings: {
            height: "",
            colorLabel: "",
            fontSizeLabel: "15",
            colorValue: "",
            fontSizeValue: "40px",
            backgroundColor: "",
            borderColor: ""
        },
        cards: [{
                card: 1,
                settings: {
                    colorLabel: "#8e99c4",
                    fontSizeLabel: "15",
                    colorValue: "#8e99c4",
                    fontSizeValue: "40px",
                    backgroundColor: "#49547e",
                    borderColor: "#646f9b"
                },
                title: "Gesamtumsatz",
                value: "€" + shortNumbers(cnt((select Projekte).Umsatz)),
                subtitle: "€" +
                shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
                " in diesem Monat"
            }, {
                card: 2,
                settings: {
                    colorLabel: "#8e99c4",
                    fontSizeLabel: "15",
                    colorValue: "#8e99c4",
                    fontSizeValue: "40px",
                    backgroundColor: "#49547e",
                    borderColor: "#646f9b"
                },
                title: "Abgeschlossen gesamt",
                value: shortNumbers(cnt(select Projekte where Abgeschlossen != null)),
                subtitle: shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
                " in diesem Monat"
            }, {
                card: 3,
                settings: {
                    colorLabel: "#8e99c4",
                    fontSizeLabel: "15",
                    colorValue: "#8e99c4",
                    fontSizeValue: "40px",
                    backgroundColor: "#49547e",
                    borderColor: "#646f9b"
                },
                title: "Conversion Rate",
                value: round(cnt(select Projekte where Abgeschlossen != null) / cnt(select Projekte) * 100, 2) +
                "%",
                subtitle: cnt(select Projekte where Abgeschlossen != null and month(Abgeschlossen) = month(today())) /
                cnt(select Projekte where month(Abgeschlossen) = month(today())) *
                100 +
                "%" +
                " in diesem Monat"
            }]
    };
arcKPIBar(data)
```

**Enlaces adicionales: **

[> NX Custom KPI Bar ](https://www.arc-rider.de/custom-kpi-bar)