(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Histogram Chart

Overview

• The Dynamic Histogram Chart displays data distribution across categories or bins.
• It helps show frequency distributions, density, and data patterns.
• The component works with different data sources and supports mock data.
• It offers configuration options for bars, axes, legends, and filtering.
• Common use cases include age distribution, transaction sizes, time analysis, and data quality checks.

Specs

Tokens

Structure

• A Histogram Chart is a data visualization tool that shows how values are distributed across ranges or categories, called bins.

• Each bin is represented by a bar whose height indicates the number of data points within that range.

• The Histogram Chart component expects data in the following format:

  [
    { "category": "0-10", "value": 12 },
    { "category": "11-20", "value": 25 },
    { "category": "21-30", "value": 47 },
    { "category": "31-40", "value": 35 },
    { "category": "41-50", "value": 28 },
    { "category": "51-60", "value": 18 },
    { "category": "61+", "value": 9 }
  ]

• The component will automatically use the "category" field (or equivalent as specified in configuration) for the x-axis labels.
• The "value" field is used for the height of each bar.

(Configured in General)

• displayName – Sets the display name of the component shown in the structure panel. For example, "Customer Age Distribution" clearly identifies the purpose of this specific histogram in the component structure.

(Configured in Datasource Properties)

• useMockData – Determines whether sample data is used instead of an actual data source. When enabled, the histogram displays pre-defined sample data, which is useful for design and testing purposes.
• dataSourceId – Specifies the data source ID for retrieving histogram data. For example, "api/customer-age-distribution" connects the chart to an endpoint that provides the appropriate data structure for visualization.
  
  • getEntityCollectionHttpRequestParametersMap – Configures HTTP request parameters for fetching data. This allows for customizing query parameters, path variables, or body parameters that are sent when requesting data.
• dataPathExpression – Defines the path to access the actual data array when the response has a nested structure. For example, "data.analysis.distribution" allows accessing deeply nested data structures.

(Configured in Visibility)

• displayConditions – Defines conditions under which the histogram is displayed. This allows for context-aware visibility, showing the chart only when certain conditions are met (e.g., when a specific data set is selected).

Styling

(Configured in Visual Properties)

• showLegend – Determines whether the legend is displayed alongside the chart. When enabled, a legend with the data series name and corresponding color will be displayed, providing context for the histogram bars.
• barPadding – Sets the padding between bars in the histogram, specified as a number between 0 and 1. For example, setting this to "0.5" adds moderate spacing between bars for better visual distinction.
• barWidth – Defines the width of individual bars in the histogram, specified as a number. For example, setting this to "30" creates bars with a width of 30 pixels, allowing for control over the chart's density.
• ignoreEmptyPoints – Determines whether empty or null data points are displayed in the chart. When enabled, gaps in the data are omitted rather than shown as zero-height bars.
• argumentAxisTitle – Sets the title text for the horizontal (x) axis of the histogram. For example, setting this to "Age Groups" clarifies what the categories along the x-axis represent.
• valueAxisTitle – Sets the title text for the vertical (y) axis of the histogram. For example, setting this to "Number of Customers" clarifies what the height of each bar represents.
• paddingClass – Configures the padding around the component using CSS classes. For example, "p-4" adds substantial padding on all sides of the histogram component.

Customization

The histogram chart offers flexible options to adapt its appearance and behavior:

• Bar appearance – Adjust the width, padding, and color of bars.
• Axis configuration – Define clear titles and control how values are displayed.
• Legend positioning – Enable or disable the legend and choose its placement.
• Data filtering – Decide whether to display empty values or omit them.

These options make the histogram suitable for different visualization needs while keeping the layout clear and professional.

Actions & Variants

(Configured in Events)

• events – Configures events that the component can trigger and respond to.
• ON_INIT – Triggered when the component is initialized. This event can be used to perform setup operations or initial data processing.
• ON_DESTROY – Triggered when the component is removed from the DOM. This event can be used for cleanup operations or resource release.

Tests

(Configured in Testing Hooks)

• id – Specifies a unique identifier for the component, useful for programmatic access in testing or custom code.
• dataTestId – Sets a testing hook ID for automated testing, allowing test scripts to reliably identify this histogram component.
• enableAsHotspot – Enables the component as a guided tour hotspot. When enabled, this histogram can be highlighted during onboarding tours.
• guidedTourHotSpotTitle – Sets the title text displayed when this component is highlighted in a guided tour, with support for translations.
• guidedTourHotSpotDescription – Sets the descriptive text explaining the histogram's purpose during a guided tour, with support for translations.

Authorization

(Configured in Authorization)

• visibilityPolicySetId – Determines the visibility of the component based on user permissions and policy sets. For example, setting to "marketingTeamPolicy" restricts the histogram to users with marketing team privileges.

Links

• Figma: tba
• Live style guide: https://e1-dev.k8s.myapp.de/live-style-guide/other-components/histogram

Guidelines

Usage

• Use when you need to visualize a distribution across bins/categories backed by a simple data shape; provide items with category and value and label axes with argumentAxisTitle and valueAxisTitle.
• Keep the authoring surface understandable via displayName.
• Hide the chart when prerequisites aren’t met using displayConditions.
• Show or hide the legend as needed with showLegend.

Sizing & Layout

• Control density with barWidth and separation with barPadding (0–1).
• Add outer whitespace using paddingClass.
• Skip null/empty buckets with ignoreEmptyPoints.

States & Feedback

• Clarify or declutter by toggling showLegend.
• Reduce noise in sparse datasets with ignoreEmptyPoints.

Data-Driven / Conditional Behavior

• Gate rendering based on context with displayConditions.
• Improve visual stability by enabling ignoreEmptyPoints.

Visibility & Authorization

• Restrict visibility with visibilityPolicySetId.
• Combine permissions and context via visibilityPolicySetId + displayConditions.

Content & Localization

• Write short, descriptive axis titles with argumentAxisTitle and valueAxisTitle.
• Use a clear author-facing name via displayName.

Dos & Don’ts

Accessibility

• Provide guided explanations during onboarding using enableAsHotspot, guidedTourHotSpotTitle, and guidedTourHotSpotDescription. Keep it concise and scannable (short guidedTourHotSpotTitle; 1–2 sentence guidedTourHotSpotDescription).
• Expose deterministic hooks for automated a11y checks via id and dataTestId.
• Ensure testing hooks (dataTestId) are stable across releases to prevent broken a11y tests.