# Streamline.js

######

## Sleek Data Visualization in Micro Format!

Streamline.js is a lightweight, dependency-free JavaScript library for generating micro charts, often called sparklines. These small, simple charts are designed to be embedded inline with text or in small spaces where a full-sized chart would be impractical.

These compact visualizations are perfect for dashboards, reports, and anywhere you need to show trends or data patterns at a glance, without the overhead of a full charting library.

Pro Tip: Streamline works with your existing HTML elements and automatically adapts to different screen sizes through its responsive design capabilities.

## Installation

Streamline.js is available as a modern ES6 module. You can include it in your project in several ways:

#### 1. Using ES6 Modules (Recommended)

    // Import the streamline function and initialization utility
    import { streamline, initStreamlines } from './../thirdparty/streamline.es6.js';

    // To initialize all elements with .streamline class
    initStreamlines();

    // Or to manually create a chart on a specific element
    const element = document.getElementById('myChart');
    streamline(element, {
        type: 'line',
        lineColor: 'var(--primary-500)',
        fillColor: 'var(--primary-200)',
        height: 40,
        width: 200
    });

#### 2. Using in an HTML file

    <!-- Include the script -->
    <script type="module">
        import { initStreamlines } from './thirdparty/streamline.es6.js';

        document.addEventListener('DOMContentLoaded', function() {
            // Initialize all streamline charts
            initStreamlines();
        });
    </script>

#### HTML Structure

    <!-- Basic line chart -->
    <span class="streamline" data-type="line" data-line-color="var(--success-500)"
        data-fill-color="var(--success-200)" data-height="40" data-width="110" data-line-width="2">
        5,3,9,6,5,9,7,3,5,2
    </span>

    <!-- Bar chart with negative values -->
    <span class="streamline" data-type="bar" data-bar-color="var(--success-500)"
        data-neg-bar-color="var(--danger-500)" data-height="40" data-width="110"
        data-bar-width="4" data-bar-spacing="1">
        4,-3,-6,-4,-5,-4,7,-3,-5,2
    </span>

    <!-- Pie chart -->
    <span class="streamline" data-type="pie" data-width="80" data-height="80"
        data-slice-colors="var(--info-500),var(--warning-500),var(--success-200)">
        7,6,3
    </span>

Important:

- Streamline.js uses data attributes prefixed with `data-` to configure chart options directly in HTML.
- Values can be provided either inside the element or using a `data-values` attribute.
- CSS variable support allows for easy theming that matches your site's color scheme.

## Configuration Options

Streamline.js provides extensive configuration options to customize your charts. All options are optional and will fall back to sensible defaults.

    // Programmatic configuration
    streamline(element, {
        type: 'line',
        width: 200,
        height: 40,
        lineColor: 'var(--primary-500)',
        fillColor: 'var(--primary-200)',
        lineWidth: 2,
        responsive: true,
        disableTooltips: false,
        tooltipPrefix: 'Value: ',
        tooltipSuffix: ' units'
    });

    // HTML data attributes configuration
    <span class="streamline"
        data-type="line"
        data-width="200"
        data-height="40"
        data-line-color="var(--primary-500)"
        data-fill-color="var(--primary-200)"
        data-line-width="2"
        data-responsive="true"
        data-disable-tooltips="false"
        data-tooltip-prefix="Value: "
        data-tooltip-suffix=" units">
        5,3,9,6,5,9,7,3,5,2
    </span>

Option | Default Value | Description | Applicable Types
--- | --- | --- | ---
`type` | 'line' | Chart type: line, bar, tristate, discrete, pie | All
`width` | 'auto' | Width of the chart in pixels. 'auto' uses container width. | All
`height` | 'auto' | Height of the chart in pixels. 'auto' uses container height. | All
`responsive` | true | Enables/disables responsive resizing when container changes. | All
`lineColor` | 'var(--primary-500)' | Color of the line in line charts. | line, discrete
`fillColor` | 'var(--primary-100)' | Fill color below the line. Set to 'transparent' for no fill. | line
`lineWidth` | 2 | Width of the line in pixels. | line, discrete
`barColor` | 'var(--primary-500)' | Color of the bars in bar charts. | bar
`negBarColor` | 'var(--danger-500)' | Color of negative value bars. | bar
`barWidth` | 4 | Width of each bar in pixels. | bar, tristate
`barSpacing` | 1 | Space between bars in pixels. | bar, tristate
`posBarColor` | 'var(--success-500)' | Color for positive (1) values in tristate charts. | tristate
`zeroBarColor` | 'var(--bs-secondary)' | Color for neutral (0) values in tristate charts. | tristate
`thresholdValue` | 0 | Threshold value for discrete charts. Lines with values above this will use the main color. | discrete
`thresholdColor` | 'var(--bs-secondary)' | Color for lines below the threshold value. | discrete
`sliceColors` | [] | Array of colors for pie chart slices. Can be a comma-separated string in HTML attributes. | pie
`disableTooltips` | false | Disables interactive tooltips on hover. | All
`tooltipPrefix` | '' | Text to display before the value in tooltips. | All
`tooltipSuffix` | '' | Text to display after the value in tooltips. | All
`tooltipOffsetX` | 10 | Horizontal offset for tooltips in pixels. | All
`tooltipOffsetY` | -20 | Vertical offset for tooltips in pixels. | All

Pro Tip: When using CSS variables for colors, Streamline.js automatically resolves them to their actual color values for proper rendering in SVG elements.

## Chart Types

Streamline.js supports various chart types to visualize different kinds of data:

#### Line Charts

Line charts display data points connected by straight line segments. They're perfect for showing trends over time.

    <span class="streamline" data-type="line" data-line-color="var(--success-500)"
        data-fill-color="var(--success-200)" data-height="40" data-width="110" data-line-width="2">
        5,3,9,6,5,9,7,3,5,2
    </span>

#### Area Charts

Area charts are line charts with the area below the line filled with a color, emphasizing volume or magnitude.

    <span class="streamline" data-type="line" data-line-color="var(--info-500)"
        data-fill-color="var(--info-200)" data-height="40" data-width="110">
        5,3,2,-1,-3,-2,2,3,5,2
    </span>

#### Bar Charts

Bar charts display data as vertical bars, great for comparing values across categories.

    <span class="streamline" data-type="bar" data-bar-color="var(--primary-500)"
        data-height="40" data-width="110" data-bar-width="4" data-bar-spacing="1">
        5,3,9,6,5,9,7,3,5,2
    </span>

#### Tristate Charts

Tristate charts represent data with three possible states: positive (1), neutral (0), and negative (-1).

    <span class="streamline" data-type="tristate" data-height="40" data-width="110"
        data-bar-width="8" data-bar-spacing="2" data-pos-bar-color="var(--success-500)"
        data-neg-bar-color="var(--danger-500)" data-zero-bar-color="var(--secondary)">
        1,1,0,1,-1,-1,1,-1,0,0,1,1
    </span>

#### Discrete Charts

Discrete charts display data as individual vertical lines, useful for showing distribution or frequency.

    <span class="streamline" data-type="discrete" data-line-color="var(--primary-500)"
        data-threshold-color="var(--danger-500)" data-threshold-value="5"
        data-height="40" data-width="110" data-line-width="2">
        5,9,7,6,5,3,2,5,8,9,7,5
    </span>

#### Pie Charts

Pie charts show data as proportional slices of a whole, ideal for displaying part-to-whole relationships.

    <span class="streamline" data-type="pie" data-width="80" data-height="80"
        data-slice-colors="var(--info-500),var(--warning-500),var(--success-200)">
        7,6,3
    </span>

## API Methods

Streamline.js exposes several methods for programmatic control:

    // Import the library
    import { streamline, initStreamlines } from './thirdparty/streamline.es6.js';

    // Initialize all streamline charts
    initStreamlines();

    // Create a chart on a specific element
    const element = document.getElementById('myChart');
    streamline(element, {
        type: 'line',
        lineColor: 'var(--primary-500)'
    });

    // Update an existing chart with new data
    element.textContent = '5,8,9,3,5,7,2,6';
    streamline(element, {
        type: 'line',
        lineColor: 'var(--success-500)'
    });

Method | Description | Parameters | Return Value
--- | --- | --- | ---
`streamline(element, options)` | Creates or updates a chart on the specified element | element: HTMLElement or CSS selector, options: Object | HTMLElement
`streamline(element, values, options)` | Creates a chart with specific values | element: HTMLElement, values: Array, options: Object | HTMLElement
`initStreamlines()` | Initializes all elements with class "streamline" on the page | None | void

## Dynamic Updates

Streamline.js makes it easy to create real-time updating charts to display live data:

    // HTML
    <span id="updating-chart" class="streamline" data-type="line" data-line-color="var(--success-500)"
        data-fill-color="var(--success-200)" data-height="40" data-width="200" data-line-width="2">
        5,3,9,6,5,9,7,3,5,2
    </span>

    // JavaScript
    document.addEventListener('DOMContentLoaded', function() {
        // Initialize all streamline charts
        initStreamlines();

        // Get the updating chart element
        const updatingChart = document.getElementById('updating-chart');
        if (updatingChart) {
            let values = updatingChart.textContent.split(',').map(Number);

            setInterval(function() {
                // Generate a new random value between 1 and 10
                const newValue = Math.floor(Math.random() * 10) + 1;

                // Add the new value and remove the oldest one
                values.push(newValue);
                values.shift();

                // Update the chart with new data
                updatingChart.textContent = values.join(',');

                // Re-initialize the chart
                initStreamlines();
            }, 500);
        }
    });

Pro Tip: For performance-critical applications with many charts, consider using `requestAnimationFrame` for smoother updates and debounce the resize listener to prevent layout thrashing.

## Advanced Examples

#### Creating Gauges with Pie Charts

Pie charts can be used as simple gauge visualizations:

    <!-- 25% Completion Gauge -->
    <span class="streamline" data-type="pie" data-width="80" data-height="80"
        data-slice-colors="var(--primary-500),var(--bs-border-color)">1/4</span>

    <!-- 50% Completion Gauge -->
    <span class="streamline" data-type="pie" data-width="80" data-height="80"
        data-slice-colors="var(--success-500),var(--bs-border-color)">1/2</span>

    <!-- 75% Completion Gauge -->
    <span class="streamline" data-type="pie" data-width="80" data-height="80"
        data-slice-colors="var(--info-500),var(--bs-border-color)">3/4</span>

#### Combining Charts with Text

Streamline charts are perfect for embedding directly within text:

    <p>
        Revenue has been trending upward
        <span class="streamline" data-type="line" data-height="20" data-width="60"
            data-line-color="var(--success-500)">1,3,5,6,8,7,9</span>
        over the last quarter, while costs have remained relatively stable
        <span class="streamline" data-type="line" data-height="20" data-width="60"
            data-line-color="var(--info-500)">4,4,3,5,4,3,5</span>.
    </p>

#### Custom Tooltips

Enhance user experience with descriptive tooltips:

    <span class="streamline" data-type="line" data-line-color="var(--primary-500)"
        data-tooltip-prefix="Temperature: " data-tooltip-suffix="°C"
        data-height="40" data-width="150">
        18,22,26,30,28,24,20
    </span>

## Troubleshooting

Common Issues:

- Chart not displaying? Ensure your container has sufficient width and height, or specify them explicitly.
- Colors not showing? If using CSS variables, make sure they're correctly defined in your CSS.
- Pie chart slices all black? Ensure your `slice-colors` is set properly - use comma-separated format without spaces: `data-slice-colors="color1,color2,color3"`.
- Chart not updating? Verify that you're reinitializing the chart after changing the data.

#### Pie Chart Color Issues

If you're having issues with pie chart slice colors, ensure the format is correct:

    // Incorrect - using array notation in HTML attribute
    <span class="streamline" data-type="pie" data-slice-colors='["var(--primary-500)", "var(--success-500)"]'>
        30,70
    </span>

    // Correct - using comma-separated format without spaces
    <span class="streamline" data-type="pie" data-slice-colors="var(--primary-500),var(--success-500)">
        30,70
    </span>

    // Correct - when using JavaScript
    streamline(element, {
        type: 'pie',
        sliceColors: ['var(--primary-500)', 'var(--success-500)']
    });

#### Debugging Tips

- Check your browser console for any JavaScript errors
- Inspect the generated SVG elements to see if they're being created correctly
- Try with explicit width and height values to rule out sizing issues
- Verify that your data values are correctly parsed by using console.log

##### On This Page

- Introduction
- Installation
- Configuration
- Chart Types
- API Methods
- Dynamic Updates
- Advanced Examples
- Troubleshooting

#### Hi Sunny,

how can I help you today?
Analyze my data

Create a new report

Summarize my Calendar

App Builder
Unlock limitless design potential with 16+ layout combinations and extensive customization options—tailor your dashboard to fit your exact needs.
Header position fixed
Navigation full height
Navigation position fixed
Navigation collapsed
Navigation Minified
Dark Navigation
Colorblind Mode
High Contrast Mode