Configuring and displaying legends is very easy with Flotr. On this page I’ll explain how to add labels to your series, and configure the various options of the legend.

Flotr Project Page » Flotr Documentation » Configure And Style Flotr Legends

A sample legend.

Adding labels & colors

Series only show up in the legend when it has a label. Next to the label there will be a color box, which shows the color of the series. You can define a label and a color for a series like this:

var serie = {
   data: [...],
   label: ‘foobarbaz’, // => the label will be ‘foobarbaz’
   color: ‘#ff0000′  // => the color will be #ff0000 (red)
   …
};

Setting the label and color is pretty self explanatory. The color value can be passed in a couple of ways. Flotr accepts the following formats:

• rgb(num,num,num) (RGB integers)
• rgba(num,num,num,num) (RGB integers and alpha value)
• rgb(num%,num%,num%) (percentages)
• rgba(num%,num%,num%,num) (percentages and alpha value)
• #ff0000 (6 integer hex value)
• #f00 (3 integer hex value)
• aqua, azure, … , white, yellow (42 predefined color keys)

So you can pick anything you like. This counts for all colors you pass to Flotr.

Legend options

The following codeblock shows the options you can set to change the legend. A small description is written after the key:value pair.

{
	show: true,		// => setting to true will show the legend, hide otherwise
	noColumns: 1, 		// => number of colums in legend table
	labelFormatter: null, 	// => fn: string -> string
	labelBoxBorderColor: '#ccc', // => border color for the little label boxes
	container: null, 	// => container (as Prototype Element) to put legend in, null means default on top of graph
	position: 'ne', 	// => position of default legend container within plot
	margin: 5, 		// => distance from grid edge to default legend container within plot
	backgroundColor: null, 	// => null means auto-detect
	backgroundOpacity: 0.85	// => set to 0 to avoid background
},

In the next paragraphs I’ll explain some of the options above.

Formatting labels

The labelFormatter options let’s you change the format of the label. You need to pass a function that accepts a single parameter and returns a string (so fn: string -> string). The argument of the function will be a label you’ve specified in a series Object. With the labelformatter you can do actions on the label string, and return it. Then the changed label string shows up in the legend. Here’s an example:

//This function adds 'y = ' before each label.
function myLabelFunc(label){
	return 'y = ' + label;
}

var options = {
...
	legend: {labelFormatter: myLabelFunc}
...
};

In the example all labels are prepended with ‘y = ‘.

Positioning the legend

Flotr gives you an easy way to position the legend within the graph. The position property can must be a string value. When the value is a abbreviation of a cardinal direction, like ‘ne’, Flotr positions the element right for you. By default, the position is set to ‘ne’, which corresponds to ‘North-East’. You can choose between four combinations:

{
	position: 'nw', // => upper left corner
	position: 'ne', // => upper right corner
	position: 'se', // => lower right corner
	position: 'sw', // => lower left corner
}

When you combine the position property with the margin property, you can place the legend wherever you want. With this property you can set the margin css property for the legend container element.

Styling the legend with CSS

Flotr defines some classes for elements that are generated for the legend. You can use these classes to change the looks of some parts of the legend:

• flotr-legend → Legend wrapper element.
• flotr-legend-bg → Legend background element.
• flotr-legend-color-box → Legend color box.
• flotr-legend-label → Legend label.

Note that you can also use the backgroundColor, backgroundOpacity and labelBoxBorderColor properties to style some parts using javascript.