Class ChartLegendSettings

Represents the settings for a chart legend.

Inheritance

System.Object

ChartSubComponent

ChartLegendSettings

Namespace: Syncfusion.Blazor.Charts

Assembly: Syncfusion.Blazor.dll

Syntax

public class ChartLegendSettings : ChartSubComponent, ISubcomponentTracker, ILegendBase

Constructors

ChartLegendSettings()

Declaration

public ChartLegendSettings()

Properties

AccessibilityDescriptionFormat

Gets or sets the format for the legend item accessibility description of the ChartLegendSettings.

Declaration

public string AccessibilityDescriptionFormat { get; set; }

Property Value

Type	Description
System.String	Accepts a string that defines the format for the legend item accessibility description of the ChartLegendSettings. The default value is null.

Remarks

Use this property to specify a format for the legend item accessibility description of the ChartLegendSettings. The placeholder ${value} can be used to set the accessibility text for the legend item. For example, the format "Selected the ${value} legend" will read as "Selected the Product A legend" for the legend item with text "Product A".

Examples

// This example demonstrates how to set the accessibility description format for the legend items in a chart.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
        <ChartSeries DataSource="@MedalDetails" Name="Silver" XName="Country" YName="Silver" />
        <ChartSeries DataSource="@MedalDetails" Name="Bronze" XName="Country" YName="Bronze" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" AccessibilityDescriptionFormat="Selected the ${value} legend" />
</SfChart>

AccessibilityRole

Gets or sets the accessibility role for the ChartLegendSettings.

Declaration

public string AccessibilityRole { get; set; }

Property Value

Type	Description
System.String	Accepts a string that defines the accessibility role for the ChartLegendSettings. The default value is null.

Remarks

Use this property to provide an accessibility role for the ChartLegendSettings.

Examples

// This example demonstrates how to set the accessibility rolefor the legend items in a chart.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
        <ChartSeries DataSource="@MedalDetails" Name="Silver" XName="Country" YName="Silver" />
        <ChartSeries DataSource="@MedalDetails" Name="Bronze" XName="Country" YName="Bronze" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" AccessibilityRole="Legend" />
</SfChart>

Alignment

Gets or sets the alignment of the legend.

Declaration

public Alignment Alignment { get; set; }

Property Value

Type	Description
Alignment	One of the Alignment enumerations that specifies the legend alignment. Options include: Near: Aligns the legend to the left or top based on the Position. Center: Aligns the legend to the center of the chart. Far: Aligns the legend to the right or bottom based on the Position. The default value is Alignment.Center.

Remarks

The alignment of the legend works as follows:

• Near: Aligns the legend to the top-left of the chart if Position is LegendPosition.Top and to the right-top of the chart if Position is LegendPosition.Right.
• Center: Aligns the legend to the top center of the chart if Position is LegendPosition.Top and to the right center of the chart if Position is LegendPosition.Right.
• Far: Aligns the legend to the top-right of the chart if Position is LegendPosition.Top and to the right-bottom of the chart if Position is LegendPosition.Right.

Examples

// This example demonstrates how to set the alignment of the legend of a chart.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" Alignment="Alignment.Far" />
</SfChart>

Background

Gets or sets the background color of the chart legend area.

Declaration

public string Background { get; set; }

Property Value

Type	Description
System.String	A string value specifying the background color of the chart legend area. The default value is "transparent".

Remarks

The value can be specified in hex or rgba format, following valid CSS color string conventions.

Examples

// This example demonstrates how to set the background color of the chart legend area.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" Background="lightgray" />
</SfChart>

Border

Gets or sets an instance of ChartLegendBorder that specifies the border of the legend.

Declaration

public ChartLegendBorder Border { get; set; }

Property Value

Type	Description
ChartLegendBorder	The default value is an instance of ChartLegendBorder.

Remarks

Use this property to customize the border of the legend, allowing adjustments to properties such as color, width, and style to enhance visual appeal.

Examples

// This example demonstrates how to set the legend's border in a chart.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true">
        <ChartLegendBorder Color="blue" Width="2" />
    </ChartLegendSettings>
</SfChart>

Description

Gets or sets the description for accessibility purposes, particularly when focused on the legend element by screen readers.

Declaration

public string Description { get; set; }

Property Value

Type	Description
System.String	A string representing the description for legends.

Remarks

This property is primarily for enhancing accessibility, providing a textual description that screen readers can announce when the legend is focused.

EnableHighlight

Gets or sets a value indicating whether to enable highlighting when hovered over the legend element.

Declaration

public bool EnableHighlight { get; set; }

Property Value

Type	Description
System.Boolean	true if highlight options are enabled; otherwise, false. The default value is false.

Remarks

If set to true, when hovered over the legend element, the respective series will be highlighted.

Examples

// The following code snippet demonstrates how hovering over a legend item highlights the corresponding series in the chart.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" EnableHighlight="true" />
</SfChart>

Focusable

Gets or sets the accessibility keyboard navigation focus option for the ChartLegendSettings.

Declaration

public bool Focusable { get; set; }

Property Value

Type	Description
System.Boolean	Accepts the boolean value to enable or disable the keyboard navigation for the ChartLegendSettings. The default value is true.

Remarks

Use this property to toggle the keyboard navigation focus for the ChartLegendSettings.

Examples

// This example demonstrates how to enable keyboard navigation for focusable UI elements.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" Focusable="true" />
</SfChart>

Height

Gets or sets the height for the legend element.

Declaration

public string Height { get; set; }

Property Value

Type	Description
System.String	A string representing the height of the legend element. The default value is null. Based on the legend position, the height of the legend will be calculated.

Remarks

Accepts values in either pixels or percentage.

Examples

// This example demonstrates how to set the height for a legend in a chart:
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
        <ChartSeries DataSource="@MedalDetails" Name="Silver" XName="Country" YName="Silver" />
        <ChartSeries DataSource="@MedalDetails" Name="Bronze" XName="Country" YName="Bronze" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" Height="60px" />
</SfChart>

IsInversed

Gets or sets a value indicating whether to inverse legend item content (image and text).

Declaration

public bool IsInversed { get; set; }

Property Value

Type	Description
System.Boolean	true if the legend content should be inversed; otherwise, false. The default value is false.

Remarks

When set to true, the legend element will display the text before the associated shape. This is different from the default, where the shape is shown first, followed by the text.

Examples

// This example demonstrates how to set the legend the text before the associated shape.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" IsInversed="true" />
</SfChart>

ItemPadding

Gets or sets the padding between legend items.

Declaration

public double ItemPadding { get; set; }

Property Value

Type	Description
System.Double	A double representing the padding between legend items. The default value is NaN.

Remarks

This property provides the spacing between items in the legend.

Examples

// This example demonstrates how to set the spacing between items in the legend of a chart.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
        <ChartSeries DataSource="@MedalDetails" Name="Silver" XName="Country" YName="Silver" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" ItemPadding="50" />
</SfChart>

Location

Gets or sets an instance of ChartLocation that specifies the location of the legend relative to the chart. If x is set to 20, the legend will move 20 pixels to the right of the chart.

Declaration

public ChartLocation Location { get; set; }

Property Value

Type	Description
ChartLocation	The default value is an instance of ChartLocation.

Remarks

The Position must be set to LegendPosition.Custom to position the legend in the chart using the specified x and y offsets.

Examples

// This example demonstrates how to determine the x and y location of a legend based on its position in a chart.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" Position="LegendPosition.Custom">
        <ChartLocation X="30" Y="40" />
    </ChartLegendSettings>
</SfChart>

Margin

Gets or sets an instance of ChartLegendMargin which specifies the margin for the legend.

Declaration

public ChartLegendMargin Margin { get; set; }

Property Value

Type	Description
ChartLegendMargin	The default value is an instance of ChartLegendMargin allowing customization of left, right, top, and bottom margins.

Remarks

The ChartLegendMargin class provides options to customize the left, right, top, and bottom margins of the chart legend. Adjusting these margins controls the space between the legend and the surrounding elements.

Examples

// This example demonstrates how to customize the chart's surrounding space of the legend.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true">
        <ChartLegendBorder Color="blue" Width="2" />
        <ChartLegendMargin Left="30" Bottom="30" Right="30" Top="30" />
    </ChartLegendSettings>
</SfChart>

MaximumLabelWidth

Gets or sets the maximum width of the individual legend item after which they get trimmed, wrapped, or clipped.

Declaration

public double MaximumLabelWidth { get; set; }

Property Value

Type	Description
System.Double	Specifies the maximum width for the legend text. The default value is null.

Remarks

This property is used to control the maximum width of the labels in the legend items, ensuring that the text does not exceed the specified width, when TextOverflow or TextWrap properties are set.

Examples

// This example demonstrates how to set the text wrap behavior when the individual legend text overflows the legend bounds or MaximumLabelWidth.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" MaximumLabelWidth="20" />
</SfChart>

Opacity

Gets or sets the opacity of the legend background.

Declaration

public double Opacity { get; set; }

Property Value

Type	Description
System.Double	A double representing the opacity of the legend background. The default value is 1.

Remarks

The provided background color will be rendered with the applied opacity value.

Examples

// This example demonstrates how to set the opacity of the legend background in a chart.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" Background="lightgray" Opacity="0.5" />
</SfChart>

Padding

Gets or sets the padding around the legend collection.

Declaration

public double Padding { get; set; }

Property Value

Type	Description
System.Double	A double representing the padding around the legend collection. The default value is 8.

Remarks

This property is used to adjust the space around the legend to enhance layout.

Examples

// This example demonstrates how to adjust the space around the legend collection in a chart.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
        <ChartSeries DataSource="@MedalDetails" Name="Silver" XName="Country" YName="Silver" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" Padding="50" />
</SfChart>

Position

Gets or sets the position of the legend in the chart.

Declaration

public LegendPosition Position { get; set; }

Property Value

Type

Description

LegendPosition

One of the LegendPosition enumeration that specifies the position of the legend. The options include: Auto: Places the legend based on based on width and height Top : Displays the legend at the top of the chart. Left : Displays the legend at the left of the chart. Bottom: Displays the legend at the bottom of the chart. Right: Displays the legend at the right of the chart. Custom: Displays the legend based on the given x and y location values. The default mode is LegendPosition.Auto.

Remarks

Use this property to position the legend at the top, left, bottom, or right of the SfChart.

Examples

// This example demonstrates how to set the legend position in a chart.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" Position="LegendPosition.Top" />
</SfChart>

Reverse

Gets or sets a value indicating whether to reverse the order of legend items.

Declaration

public bool Reverse { get; set; }

Property Value

Type	Description
System.Boolean	true if the legend items should be reversed; otherwise, false. The default value is false.

Remarks

If set to true, the last series in the collection will be placed first.

Examples

// This example demonstrates how to set the legend items should be reversed.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
        <ChartSeries DataSource="@MedalDetails" Name="Silver" XName="Country" YName="Silver" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" Reverse="true" />
</SfChart>

ShapeHeight

Gets or sets the height of the legend shape.

Declaration

public double ShapeHeight { get; set; }

Property Value

Type	Description
System.Double	A double representing the height of the legend shape. The default value is 10.

Remarks

This property is used to modify the height of the legend shape.

Examples

// This example demonstrates how to customize the legend shape height in a chart.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" ShapeHeight="30" />
</SfChart>

ShapePadding

Gets or sets the padding between the legend shape and legend text.

Declaration

public double ShapePadding { get; set; }

Property Value

Type	Description
System.Double	A double representing the padding between the legend shape and legend text. The default value is 8.

Remarks

This property allows for the adjustment of space between the legend shape and the text associated with it, enhancing the visual layout of the legend.

Examples

// This example demonstrates how to set the padding between the legend shape and legend text in a chart.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" ShapePadding="20"> />
</SfChart>

ShapeWidth

Gets or sets the width of the legend shape.

Declaration

public double ShapeWidth { get; set; }

Property Value

Type	Description
System.Double	A double representing the width of the legend shape. The default value is 10.

Remarks

This property is used to modify the width of the legend shape.

Examples

// This example demonstrates how to customize the legend shape width in a chart.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" ShapeWidth="30" />
</SfChart>

TabIndex

Gets or sets the tabindex value of the legend for accessibility purposes.

Declaration

public double TabIndex { get; set; }

Property Value

Type	Description
System.Double	A double representing the tabindex value for the legend. The default value is 3.

Remarks

This property is intended to provide a textual description of the legend for assistive technologies, improving accessibility for users with disabilities.

Examples

// This example demonstrates how to set the tabindex value of the legend for accessibility purposes.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" TabIndex="0" />
</SfChart>

TextOverflow

Gets or sets the text overflow behavior to employ when the individual legend text overflows the legend bounds or MaximumLabelWidth.

Declaration

public LabelOverflow TextOverflow { get; set; }

Property Value

Type	Description
LabelOverflow	One of the LabelOverflow enumeration values that specifies the text overflow option. The options include: LabelOverflow.Ellipse: Trims the text if it exceeds the defined margins. TextOverflow.Clip: Shows the text as it is. The default value is Ellipse.

Remarks

This property manages how text should behave when it's too long for its allocated space, either by trimming, wrapping, or displaying fully.

Examples

// This example demonstrates how to set the text overflow behavior to employ when the individual legend text overflows the legend bounds or MaximumLabelWidth.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
        <ChartSeries DataSource="@MedalDetails" Name="Silver" XName="Country" YName="Silver" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" TextOverflow="Syncfusion.Blazor.LabelOverflow.Ellipse" MaximumLabelWidth="20" />
</SfChart>

TextStyle

Gets or sets an instance of ChartLegendTextStyle that specifies the text style of the legend.

Declaration

public ChartLegendTextStyle TextStyle { get; set; }

Property Value

Type	Description
ChartLegendTextStyle	The default value is an instance of ChartLegendTextStyle.

Remarks

The legend text font and alignment can be customized using this instance of ChartLegendTextStyle.

Examples

// This example demonstrates how to customize the legend text in a chart.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true">
        <ChartLegendTextStyle 
            Size="14px" 
            Color="blue" 
            FontFamily="Roboto" 
            FontWeight="400" 
            FontStyle="Normal" 
            Opacity="1" 
            TextAlignment="Alignment.Center" 
            TextOverflow="TextOverflow.Trim" />
    </ChartLegendSettings>
</SfChart>

TextWrap

Gets or sets the text wrap behavior when the individual legend text overflows the legend bounds or MaximumLabelWidth.

Declaration

public TextWrap TextWrap { get; set; }

Property Value

Type	Description
TextWrap	One of the TextWrap enumeration values that specify the text wrap option. The default value is Normal.

Remarks

This property is applicable only when TextOverflow is set to LabelOverflow.Ellipse.

Examples

// This example demonstrates how to set the text wrap behavior when the individual legend text overflows the legend bounds or MaximumLabelWidth.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" TextWrap="Syncfusion.Blazor.TextWrap.Normal" MaximumLabelWidth="20" />
</SfChart>

ToggleVisibility

Gets or sets a value indicating whether the series' visibility collapses on the legend click.

Declaration

public bool ToggleVisibility { get; set; }

Property Value

Type	Description
System.Boolean	true if the series' visibility collapses on the legend click; otherwise, false. The default value is true.

Remarks

This property allows users to toggle the visibility of chart series by clicking on the corresponding legend item, enhancing interactivity and user experience.

Examples

// This example demonstrates how to set the visibility of chart series by clicking on the corresponding legend item.
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" ToggleVisibility="true" />
</SfChart>

Visible

Gets or sets a value indicating the visibility of the legend.

Declaration

public bool Visible { get; set; }

Property Value

Type	Description
System.Boolean	true if the legend is visible; otherwise, false. The default value is true.

Remarks

This property controls the display of the chart legend.

Examples

// The following code snippet demonstrates how to set the visibility of the legend in an chart:
<SfChart>        
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" />
</SfChart>

Width

Gets or sets the width for the legend.

Declaration

public string Width { get; set; }

Property Value

Type	Description
System.String	A string representing the width of the legend. Based on the legend position, the width will be calculated. The default value is null.

Remarks

Accepts values in either pixels or percentage.

Examples

// This example demonstrates how to set the width for a legend in a chart:
<SfChart>
    <ChartSeriesCollection>
        <ChartSeries DataSource="@MedalDetails" Name="Gold" XName="Country" YName="Gold" />
        <ChartSeries DataSource="@MedalDetails" Name="Silver" XName="Country" YName="Silver" />
        <ChartSeries DataSource="@MedalDetails" Name="Bronze" XName="Country" YName="Bronze" />
    </ChartSeriesCollection>
    <ChartLegendSettings Visible="true" Width="60px" />
</SfChart>