# Banded List

Learn how to use the BandedList report item in ActiveReportsJS.

## Content

A `Banded List` report item is a [data region](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Data-Regions) that visualizes the bound data by producing a series of sections called `bands`. A band is the container for [data visualizers](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Data-Visualizers) such as a [TextBox](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Data-Visualizers/TextBox) or [Image](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Data-Visualizers/Image) arranged in a free-form layout fashion.

You can use the banded list to build a `Banded Report`. Visit the [Get Started With Banded Reports](/activereportsjs/docs/v6.1/ReportAuthorGuide/QuickStart/get-started-with-/Get-Started-With-Banded-Reports) tutorial for more information.

### Adding a Banded List

You can add a `Banded List` into a report by either double-click the corresponding item in the [toolbox](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Designer-Interface#toolbox) or drag-and-drop it to a report page area.
DOC-DETAILS-TAG-OPEN
DOC-SUMMARY-TAG-OPEN
Expand to watch adding the Banded List in action
DOC-SUMMARY-TAG-CLOSE
![AddingBandedList](https://cdn.mescius.io/document-site-files/images/fcb03d52-fb54-40c3-8356-825c2a095d5b/AddingBandedList.91d495.gif)
DOC-DETAILS-TAG-CLOSE

### Banded List Designer

The following diagram depicts the default structure of the banded list designer that appears if you click anywhere inside its bounding box.

![](https://cdn.mescius.io/document-site-files/images/e637becb-8cbc-4561-bac1-84462097b057/reportauthor-guide/BandedList/banded-list-designer.png)

### General Banded List Configuration

You can use one of two methods to load the general banded list configuration into the [properties panel](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Designer-Interface#properties-panel)

* Select the banded list item in the [report explorer](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Designer-Interface#report-explorer).
* Click the `Root handler` in the banded list [designer](/activereportsjs/docs/v6.1/#banded-list-designer).

The general configuration includes [Base Report Item properties](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Common-Properties#base-properties), [Common Style Properties](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Common-Properties#style-properties), [Data Region properties](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Data-Regions#common-properties), [Visibility](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Common-Properties#visibility), [Page Break](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Common-Properties#page-break), and the following specific properties.

* If a banded list starts at the bottom of the page, then its [header band](/activereportsjs/docs/v6.1/#header) could appear by itself. You can turn on the `Prevent Orphaned Header` switch to move a "lonely" header to the next page so that it appears together with other sections.
* Sometimes the [footer band](/activereportsjs/docs/v6.1/#footer) could appear by itself on the top of the page. You can turn on the `Prevent Orphaned Footer` switch to move a previous section to the next page so that it appears together with a "lonely" footer.
* The `Keep together` flag determines whether a banded list always appears on a single page if it fits.
* The `Consume White Space` flag indicates whether banded list sections that can shrink in size should eliminate the whitespace.

### Banded List Sections

The banded list consists of sections called `bands`. Several band types serve different purposes but share common properties. You can click the `Band Handler` in the banded list [designer](/activereportsjs/docs/v6.1/#banded-list-designer) or anywhere inside the bounding box of a band to load its configuration into the properties panel.

* The `Height` is the vertical size, in [length](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Common-Properties#length) units, of a band at the design-time.
* The `Action` property determines the [interactive action](/activereportsjs/docs/v6.1/ReportAuthorGuide/Interactivity) that occurs when a report reader clicks within the space occupied by a band.
* The `Can Grow` flag indicates whether a band can increase its height at preview-time to accommodate growing content, such as a long text.
* The `Can Shrink` flag indicates whether a band can shrink in height if there is more available space than the content takes. This property works together with the [Consume White Space](/activereportsjs/docs/v6.1/#consume-white-space) flag.
* The `Keep Together` flag indicates whether a band always appears on a single page if it fits.
* The `Page Break` property determines the location of page breaks generated by band instances.
    * `None` \- no page breaks are generated\.
    * `Start` \- each band instance inserts the page break before displaying the content\.
    * `End` \- each band instance inserts the page break after displaying the content \.
    * `StartAndEnd` \- the combination of the `Start` and `End` options.
* The [Visibility](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Common-Properties#visibility) configures a band's static or dynamic visibility.

### Header

The `Header` appears at the beginning of a banded list. Also, if its `Repeat On New Page` switch is on, it prints on every page taken by the banded list content. You could use the header band to display the title or the logo of a banded report. For instance, the `Get Started with Banded Reports` [demo](/activereportsjs/demos/Reports/GetStartedWithBandedReports/purejs) contains the `Employee Directory` [textbox](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Data-Visualizers/TextBox) in the header band.

### Group Header

The `Group Header` appears at the beginning of a [group instance](/activereportsjs/docs/v6.1/#banded-list-grouping). Also, if its `Repeat On New Page` switch is on, it prints on every page taken by the banded list content. You could use the group header band to display the group's field value or summary value. For instance, the `Get Started with Banded Reports` [demo](/activereportsjs/demos/Reports/GetStartedWithBandedReports/purejs) groups employees by the department name and has the group header that prints on every page and contains the `{DepartmentName}` textbox.

### Details

The `Details` section repeats for each [bound data set](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Data-Regions#data-set-name) record that passed through the [data set filters](/activereportsjs/docs/v6.1/ReportAuthorGuide/Databinding#data-set-filters) and [data region filters](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Data-Regions#common-properties). For instance, in the `Get Started with Banded Reports` [demo](/activereportsjs/demos/Reports/GetStartedWithBandedReports/purejs), the details band displays the name, title, email, phone and photo of each employee.

If a banded list has the [grouping](/activereportsjs/docs/v6.1/#banded-list-grouping) configured, then the details bands appear between the header and footer of the enclosing [group instance](/activereportsjs/docs/v6.1/#banded-list-grouping).

### Group Footer

The `Group Footer` appears at the end of a [group instance](/activereportsjs/docs/v6.1/#banded-list-grouping). Also, if its `Repeat On New Page` switch is on, it prints on every page taken by the banded list content. You could use the group footer band to display summary values. Also, you could turn on the `Print At Bottom` switch to ensure that the group footer always prints at the bottom of the page.

### Footer

The `Footer` band appears at the end of a banded list. Also, if its `Repeat On New Page` switch is on, it prints on every page taken by the banded list content. You could use the footer band to display grand totals. Also, you could turn on the `Print At Bottom` switch to ensure that the footer band always prints at the bottom of the page.

### Banded List Grouping

The banded list allows you to group `Details` bands by one or multiple criteria. For instance, the `Get Started with Banded Reports` [demo](/activereportsjs/demos/Reports/GetStartedWithBandedReports/purejs) groups the employee list by the department name. We recommend using the `Group Editor` in the banded list [designer](/activereportsjs/docs/v6.1/#banded-list-designer) to configure grouping.

### Adding Groups

You can use one of two methods to add a banded list group.

* Right-click the `<Details>` text in the `Group Editor` and select the `Group -> Insert Group` item in the context menu.
* Drag and drop a field that you want to group by from the [Data panel](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Designer-Interface#data-panel) to the `Group Editor`.

DOC-DETAILS-TAG-OPEN
DOC-SUMMARY-TAG-OPEN
Expand to watch adding grouping by drag-and-drop in action
DOC-SUMMARY-TAG-CLOSE
![](https://cdn.mescius.io/document-site-files/images/e637becb-8cbc-4561-bac1-84462097b057/reportauthor-guide/GetStartedWithBandedReports/GroupingData.gif)
DOC-DETAILS-TAG-CLOSE

### Insert child or parent groups

You can arrange data in a banded list with several nested groups. For instance, in the `Get Started with Banded Reports` [demo](/activereportsjs/demos/Reports/GetStartedWithBandedReports/purejs), employees within each department could be grouped by the job title.

To insert a child group, right-click the parent group name in the `Group Editor` and select the `Group -> Insert Group` item in the context menu. Alternatively, you can drag-and-drop a field from the data panel to the group editor that indicates the position of a newly added group relative to existing groups with the `<New Group>` placeholder.

Also, you could delete a group or remove or add its [header](/activereportsjs/docs/v6.1/#group-header) or [footer](/activereportsjs/docs/v6.1/#group-footer) by using the corresponding items of the context menu.

![](https://cdn.mescius.io/document-site-files/images/e637becb-8cbc-4561-bac1-84462097b057/reportauthor-guide/BandedList/group-context-menu.png)

### Group Configuration

The `Group Editor` enumerates group names that you can click to load their configuration into the [properties panel](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Designer-Interface#properties-panel).

* The `Group Name` is the group `Id` that displayed in the group editor.
* The `Group Expressions` is the [collection](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Common-Properties#collection) of [bound field references](/activereportsjs/docs/v6.1/ReportAuthorGuide/Expressions/references#data-set-fields) or more advanced expressions. Distinct values of group expressions generate `Group Instances` that consist of optional `Group Header` and `Group Footer` and the `Details` bands. For instance, the `Get Started with Banded Reports` [demo](/activereportsjs/demos/Reports/GetStartedWithBandedReports/purejs) has the `{DepartmentName}` group expression. Consequently, the banded list generates 17 group instances.
* The `Label` [expression](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Common-Properties#expression) determines the text of a group instance link in the [Report Map](/activereportsjs/docs/v6.1/ReportAuthorGuide/Interactivity#report-map). The `Get Started with Banded Reports` demo uses this property.
* The [Filters Editor](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Designer-Interface#filters-editor) allows you to filter out certain group instances. For example, if we want to exclude the `Sales` department from the `Get Started with Banded Reports` demo's output, then we can add the following filter for the `DepartmentName` group.

![](https://cdn.mescius.io/document-site-files/images/e637becb-8cbc-4561-bac1-84462097b057/reportauthor-guide/BandedList/group-filter.png)

* The `Sort Expressions` is the [collection](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Common-Properties#collection) of items that allows you to sort group instances. Each item consists of the [expression](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Common-Properties#expression) and the sort direction. For example, in the `Get Started with Banded Reports` demo, we could sort the `DepartmentName` group instances in ascending or descending alphabetical order by using the `{DepartmentName}` sort expression and required sort direction.

### Group Layout Configuration

* If a group instance starts at the bottom of the page, its `Header` band could appear by itself. You can switch on the `Prevent Orphaned Header` flag to move "lonely" group headers to the next page so that they appear together with the first `Details` band of the group instance.
* Sometimes, the `Group Footer` band could appear by itself on the top of the page. You can switch on the `Prevent Orphaned Footer` flag to move the last `Details` band of the group instance to the next page so that it appears together with a "lonely" group footer.
* The `Keep together` flag ensures that the group instance always appears on a single page if it fits.
* The `Page Break` property determines the location of page breaks generated by group instances.
    * `None` \- no page breaks are generated\.
    * `Start` \- each group instance inserts the page break before the `Group Header` or the first `Details` band.
    * `End` \- each group instance inserts the page break after the `Group Footer` or the last `Details` band.
    * `StartAndEnd` \- the combination of the `Start` and `End` options.
    * `Between` \- each group instance starts on the new page\. The `Get Started with Banded Reports` [demo](/activereportsjs/demos/Reports/GetStartedWithBandedReports/purejs) uses this option.
* The [Visibility](/activereportsjs/docs/v6.1/ReportAuthorGuide/Report-Items/Common-Properties#visibility) property determines static or dynamic visibility of group instances.
* The `New Section` flag determines whether each group instance has its page numbering. Check the [Global References](/activereportsjs/docs/v6.1/ReportAuthorGuide/Expressions/references#page-numbering) documentation for more information.