BarChartDocumentation.razor

@attribute [Route(pageUrl)]
@attribute [Route(pageUrl2)]
@layout DemosMainLayout

<PageMetaTags PageUrl="@pageUrl" Title="@metaTitle" Description="@metaDescription" ImageUrl="@imageUrl" />

<PageHero Title="@pageTitle">
    <SubTitleTemplate>
        @((MarkupString)pageDescription)
    </SubTitleTemplate>
</PageHero>

<DocsLink Href="@DemoRouteConstants.Docs_BarChart" />

<Prerequisites PageUrl="@pageUrl" />

<Section Class="p-0" Size="HeadingSize.H4" Name="How it works" PageUrl="@pageUrl" Link="how-it-works">
    <Block>
        The <strong>Bar Chart</strong> component visualizes data as vertical bars, making it easy to compare values across categories or track changes over time.
        <br /><br />
        <strong>How to use:</strong>
        <div class="content">
            <ol>
                <li>Add the <code>BarChart</code> component to your page.</li>
                <li>Provide <code>Labels</code> for the X-axis categories and one or more <code>Datasets</code> for the Y-axis values.</li>
                <li>Customize appearance and behavior using the <code>Options</code> property (e.g., colors, tooltips, axis settings).</li>
                <li>Refer to the demo code for examples of basic and advanced usage, including multiple datasets and custom styling.</li>
            </ol>
        </div>
        This demo showcases the essential setup for a bar chart and demonstrates how to bind your data for quick visualization.
    </Block>
    <Demo Type="typeof(BarChart_Demo_01_Examples)" Tabs="true" />
</Section>

<Section Class="p-0" Size="HeadingSize.H4" Name="Combo bar/line" PageUrl="@pageUrl" Link="combo-bar-line">
    <Block>
        The <strong>Combo bar/line</strong> demo mixes <code>BarChartDataset</code> and <code>LineChartDataset</code> in the same <code>BarChart</code>.
        <br /><br />
        <strong>How to use:</strong>
        <div class="content">
            <ol>
                <li>Use the <code>BarChart</code> component as the root chart.</li>
                <li>Add both <code>BarChartDataset</code> and <code>LineChartDataset</code> instances to the same <code>ChartData.Datasets</code> collection.</li>
                <li>Configure interaction options such as <code>Mode = InteractionMode.Index</code> and <code>Intersect = false</code> for a combined tooltip experience.</li>
                <li>Refer to the demo code below for a working example with bar columns and a line overlay.</li>
            </ol>
        </div>
    </Block>
    <Demo Type="typeof(BarChart_Demo_09_Combo_Bar_Line)" Tabs="true" />
</Section>

<Section Class="p-0" Size="HeadingSize.H4" Name="Horizontal bar chart" PageUrl="@pageUrl" Link="horizontal-bar-chart">
    <Block>
        The <strong>Horizontal Bar Chart</strong> displays data values as horizontal bars, making it ideal for comparing categories with long labels or when you want to emphasize comparison between values.
        <br /><br />
        <strong>How to use:</strong>
        <div class="content">
            <ol>
                <li>Use the <code>BarChart</code> component and set the <code>IndexAxis</code> option to <code>'y'</code> to render bars horizontally.</li>
                <li>Provide your data and labels as you would for a standard bar chart.</li>
                <li>Customize colors and appearance using the available palette utilities or your own color set.</li>
            </ol>
        </div>
        Refer to the demo code below for a working example and configuration options.
    </Block>
    <Demo Type="typeof(BarChart_Demo_02_Horizontal_BarChart)" Tabs="true" />
</Section>

<Section Class="p-0" Size="HeadingSize.H4" Name="Stacked bar chart" PageUrl="@pageUrl" Link="stacked-bar-chart">
    <Block>
        The <strong>Stacked Bar Chart</strong> allows you to display multiple data series stacked on top of each other, making it easy to compare the total and individual contributions of each series for every category.
        <br /><br />
        <strong>How to use:</strong>
        <div class="content">
            <ol>
                <li>Use the <code>BarChart</code> component and configure the <code>Options.Scales.X.Stacked</code> and <code>Options.Scales.Y.Stacked</code> properties to <code>true</code> to enable stacking.</li>
                <li>Provide multiple datasets in your chart data, each representing a different series to be stacked.</li>
                <li>Customize colors for each dataset using palette utilities or your own color set for better distinction.</li>
                <li>Refer to the demo code below for a working example and further configuration options.</li>
            </ol>
        </div>
    </Block>
    <Demo Type="typeof(BarChart_Demo_03_Stacked_BarChart)" Tabs="true" />
</Section>

<Section Class="p-0" Size="HeadingSize.H4" Name="Stacked bar chart with data labels" PageUrl="@pageUrl" Link="stacked-bar-chart-with-data-labels">
    <Block>
        The <strong>Stacked Bar Chart with Data Labels</strong> enhances the standard stacked bar chart by displaying value labels directly on each bar segment. This makes it easier to read and compare the values of each dataset within a category.
        <br /><br />
        <strong>How to use:</strong>
        <ul>
            <li>Use the <code>BarChart</code> component and enable stacking by setting <code>Options.Scales.X.Stacked</code> and <code>Options.Scales.Y.Stacked</code> to <code>true</code>.</li>
            <li>Add multiple datasets to your chart data to represent different series.</li>
            <li>Enable data labels by configuring the chart's plugins, such as <code>Options.Plugins.Datalabels.Display = true</code>.</li>
            <li>Customize the appearance and formatting of data labels as needed for your scenario.</li>
        </ul>
        Refer to the demo code below for a working example and further configuration options.
    </Block>
    <Demo Type="typeof(BarChart_Demo_04_Stacked_BarChart_with_Datalabels)" Tabs="true" />
</Section>

<Section Class="p-0" Size="HeadingSize.H4" Name="Locale" PageUrl="@pageUrl" Link="locale">
    <Block>
        The <strong>Locale</strong> demo shows how to localize number and date formatting in your bar chart.
        <br /><br />
        <strong>How to use:</strong>
        <div class="content">
            <ol>
                <li>Set the <code>Locale</code> property on the <code>BarChart</code> component to your desired culture code (e.g., <code>"fr-FR"</code> for French).</li>
                <li>Number and date labels in the chart will automatically format according to the specified locale.</li>
                <li>This is useful for displaying charts to users in different regions with appropriate formatting.</li>
            </ol>
        </div>
        Refer to the demo code below for a working example and configuration options.
    </Block>
    <Demo Type="typeof(BarChart_Demo_05_Locale)" Tabs="true" />
</Section>

<Section Class="p-0" Size="HeadingSize.H4" Name="Border radius" PageUrl="@pageUrl" Link="border-radius">
    <Block>
        The <strong>Border Radius</strong> feature allows you to create bar charts with rounded corners, giving your charts a modern and visually appealing look. This is especially useful for dashboards and applications where aesthetics are important.
        <br /><br />
        <strong>How to use:</strong>
        <div class="content">
            <ol>
                <li>Add the <code>BarChart</code> component to your page.</li>
                <li>When defining each <code>BarChartDataset</code>, set the <code>BorderRadius</code> property to a list of pixel values (e.g., <code>new List&lt;double&gt; { 10 }</code>) to control the roundness of the bar corners.</li>
                <li>Optionally, set <code>BorderSkipped = false</code> to apply the border radius to all corners of each bar.</li>
                <li>Customize other appearance options such as <code>BackgroundColor</code> and <code>BorderColor</code> as needed.</li>
                <li>Refer to the demo code below for a working example and further customization options.</li>
            </ol>
        </div>
        Using the <code>BorderRadius</code> property, you can easily enhance the style of your bar charts to better match your application's design.
    </Block>
    <Demo Type="typeof(BarChart_Demo_06_Border_Radius)" Tabs="true" />
</Section>

<Section Class="p-0" Size="HeadingSize.H4" Name="Animations - Delay" PageUrl="@pageUrl" Link="animations-delay">
    <Block>
        The <strong>Animations - Delay</strong> demo illustrates how to add a delay to the animation of your Bar Chart, making the chart elements appear with a timed entrance effect. This is useful for drawing attention to the chart as it loads or for creating a more engaging user experience.
        <br /><br />
        <strong>How to use:</strong>
        <div class="content">
            <ol>
                <li>Add the <code>BarChart</code> component to your page and define your <code>Labels</code> and <code>Datasets</code> as usual.</li>
                <li>Configure the <code>Options.Animation</code> property by setting the <code>Duration</code> (in milliseconds) and <code>Delay</code> (in milliseconds) to control the timing of the animation.</li>
                <li>Bind your <code>chartData</code> and <code>barChartOptions</code> to the <code>BarChart</code> component.</li>
                <li>Refer to the demo code below for a working example of how to set up and customize animation delays.</li>
            </ol>
        </div>
        Animation delays help you create visually appealing transitions and can be tailored to fit your application's style.
    </Block>
    <Demo Type="typeof(BarChart_Demo_07_Animations_A_Delay)" Tabs="true" />
</Section>

<Section Class="p-0" Size="HeadingSize.H4" Name="Animations - DataSet level delay" PageUrl="@pageUrl" Link="animations-dataset-level-delay">
    <Block>
        The <strong>Animations - DataSet Level Delay</strong> demo demonstrates how to apply different animation delays to each dataset in your Bar Chart. This allows each dataset to animate in sequence, making comparisons clearer and adding a dynamic effect to your data presentation.
        <br /><br />
        <strong>How to use:</strong>
        <div class="content">
            <ol>
                <li>Add the <code>BarChart</code> component to your page and define your <code>Labels</code> and multiple <code>Datasets</code>.</li>
                <li>For each dataset, set the <code>Animation</code> property with specific <code>Duration</code> and <code>Delay</code> values to control when each dataset animates.</li>
                <li>Bind your <code>chartData</code> and <code>barChartOptions</code> to the <code>BarChart</code> component.</li>
                <li>Refer to the demo code below for a practical example of dataset-level animation configuration.</li>
            </ol>
        </div>
        Dataset-level animation delays are ideal for highlighting differences between series and creating engaging, stepwise chart reveals.
    </Block>
    <Demo Type="typeof(BarChart_Demo_08_Animations_B_DataSet_Level_Delay)" Tabs="true" />
</Section>

@code {
    private const string pageUrl = DemoRouteConstants.Demos_BarChart;
    private const string pageUrl2 = DemoRouteConstants.Demos_Prefix;
    private const string pageTitle = "Bar Chart";
    private const string pageDescription = "The <code>Blazor Bar Chart</code> component displays data values as vertical bars, making it easy to compare multiple data sets or visualize trends over time.";
    private const string metaTitle = "Blazor Bar Chart";
    private const string metaDescription = "The Blazor Bar Chart component displays data values as vertical bars, making it easy to compare multiple data sets or visualize trends over time.";
    private const string imageUrl = @DemoImageSrcConstants.BarChart;
}