View Options
The Display popover of a collection: layout, grouping, ordering on several levels, Show switches and visible properties, reported as one plain value.
c2-view-options
The "Display" popover of a collection: which layout it uses, what it is grouped and sub-grouped by, how it is
ordered (several levels), which kinds of items it includes and which properties each item shows. The component
holds no data and renders no items; it edits one ViewOptionsValue and fires view-change, and the app applies the
value to whatever draws the collection. orderBy has the shape of c2-table's sortModel, groupBy feeds its
group-by and properties its columns' hidden.
Fields come from c2-view-field children or from the fields array, which wins when both are present and shares
id, label and icon with c2-filter-builder's fields. The Show switches come from c2-view-toggle children or
the toggles array the same way. A section with nothing to offer is left out.
The component stores nothing: keep value wherever the app keeps settings. With default-value set, Reset returns
to it and the host matches :state(changed) while the value differs (the default trigger shows a dot). On a board
layout, Grouping and Sub-grouping read Columns and Rows.
The trigger is slotted into trigger; without one a "Display" button is drawn. The panel is a non-modal dialog on
the top layer, positioned by c2-overlay: Escape and a click outside close it and focus returns to the trigger.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
value | Partial<ViewOptionsValue> | undefined | undefined | The view being edited. JSON as an attribute. Missing keys fall back to the first layout, no grouping, no ordering, each toggle's checked and every property field. |
default-value | Partial<ViewOptionsValue> | undefined | undefined | What Reset returns to, and what the value is compared with for :state(changed). JSON as an attribute. Without it there is no Reset. |
fields | ViewFieldConfig[] | undefined | undefined | Fields to offer. JSON as an attribute. Replaces the c2-view-field children when set. |
toggles | ViewToggleConfig[] | undefined | undefined | Switches of the Show section. JSON as an attribute. Replaces the c2-view-toggle children when set. |
layouts | string[] | [] | Layout ids, space-separated: list board table gallery calendar timeline have an icon and a label; any other id is shown as written. One id (or none) hides the Layout switch. |
max-sorts | number | 3 | How many ordering levels "Add sort" allows. 1 gives a single sort. |
can-set-default | boolean | false | Show "Set as default", which fires default-request. |
open | boolean | false | Whether the panel is showing. Set it to open or close the panel from code. |
placement | Placement | bottom-end | Preferred placement of the panel next to the trigger (floating-ui names). |
Slots
| Name | Description |
|---|---|
(default) | c2-view-field and c2-view-toggle elements. They render nothing themselves. |
trigger | The element that opens the panel. Without one, a "Display" button is drawn. A c2-* trigger gets aria-haspopup and aria-expanded on its inner button; a plain element is the author's markup, so write aria-haspopup="dialog" on it yourself (aria-expanded is kept up to date once the panel has opened). |
extra | App-specific rows (density, timeline zoom) shown below the Show switches. |
Events
| Name | Type | Description |
|---|---|---|
view-change | CustomEvent<ViewChangeEventDetail> | Fired after the user edits the value. detail.value is the whole new value (already in value), detail.changed the key that changed, or null after Reset. Does not bubble. |
default-request | CustomEvent<ViewDefaultRequestEventDetail> | Fired by "Set as default" with the current value. The app decides who may save it, then sets default-value. Does not bubble. |
toggle | ToggleEvent | Fired after the panel opens or closes; newState is open or closed. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
section | Shadow DOM styling hook for the section element. |
label | Shadow DOM styling hook for the label element. |
heading | Shadow DOM styling hook for the heading element. |
footer | Shadow DOM styling hook for the footer element. |
trigger | Shadow DOM styling hook for the trigger element. |
changed | Shadow DOM styling hook for the changed element. |
panel | Shadow DOM styling hook for the panel element. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-view-options__panel--width | pixel | 320px | Width of the panel. |
--c2-view-options__panel--background | color | #ffffff | |
--c2-view-options__panel--border | border | 1px solid #e4e4e7 | |
--c2-view-options__panel--border-radius | border-radius | 8px | |
--c2-view-options__panel--box-shadow | box-shadow | 0 8px 24px rgba(24, 24, 27, 0.08) | |
--c2-view-options__panel--max-height | pixel | 640px | Tallest the panel grows before it scrolls; it also never exceeds the room beside the trigger. |
--c2-view-options__section--padding | padding | 12px | Inner padding of each section. |
--c2-view-options__section--gap | pixel | 10px | Space between the rows of a section. |
--c2-view-options__section--border-top | border | 1px solid #e4e4e7 | Line between sections. |
--c2-view-options__label--color | color | #71717a | Row labels: Grouping, Ordering. |
--c2-view-options__label--font-size | font-size | 14px | |
--c2-view-options__label--width | pixel | 104px | Width of the row label column. |
--c2-view-options__heading--color | color | #71717a | Section headings: Show, Display properties. |
--c2-view-options__heading--font-size | font-size | 12px | |
--c2-view-options__heading--font-weight | font-weight | 600 | |
--c2-view-options__heading--letter-spacing | letter-spacing | 0.06em | |
--c2-view-options__heading--text-transform | text-transform | uppercase | |
--c2-view-options__footer--background | color | transparent | |
--c2-view-options__changed--color | color | rgb(2, 101, 220) | Dot on the default trigger while the value differs from default-value. |
--c2-view-options__button--background-color | color | #ffffff | Background of the outlined buttons: the default trigger, Add sort and Reset. |
--c2-view-options__button--color | color | #18181b | Text of the outlined buttons. |
--c2-view-options__button--border | border | 1px solid #bcbcc6 | Border of the outlined buttons. |
--c2-view-options__button__hover--background-color | color | #f4f4f5 | Background of an outlined button on hover and press. |
Text and languages
The text the component shows, in English. It shows another language when the app adds one with addTranslations, under view-options, and the nearest lang asks for it; any message not translated stays in English. {0}, {1}… stand for the values a message carries. Languages guide.
| Key | English | Values |
|---|---|---|
display | Display | — |
panel | Display options | — |
layout | Layout | — |
list | List | — |
board | Board | — |
table | Table | — |
gallery | Gallery | — |
calendar | Calendar | — |
timeline | Timeline | — |
grouping | Grouping | — |
subGrouping | Sub-grouping | — |
columns | Columns | — |
rows | Rows | — |
noGrouping | No grouping | — |
noSubGrouping | No sub-grouping | — |
noRows | No rows | — |
ordering | Ordering | — |
sortField | Sort level {0} | {0} level |
ascending | Ascending | — |
descending | Descending | — |
removeSort | Remove sort level {0} | {0} level |
addSort | Add sort | — |
show | Show | — |
properties | Display properties | — |
reset | Reset | — |
setDefault | Set as default | — |
c2-view-field
One field of a c2-view-options, written in markup. Renders nothing: the parent reads it. A fields array set on
the parent replaces every c2-view-field child.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
field | string | — | Id of the field: the value stored in groupBy, orderBy[].field and properties. |
label | string | — | Text shown for the field. Defaults to the element's text, then to field. |
icon | string | — | Tag name of an icon element shown before the label, e.g. c2-feather-user. |
groupable | boolean | false | Offer the field under Grouping and Sub-grouping. |
orderable | boolean | false | Offer the field under Ordering. |
property | boolean | false | Offer the field under Display properties. |
c2-view-toggle
One switch in the Show section of a c2-view-options, written in markup. Renders nothing: the parent reads it. A
toggles array set on the parent replaces every c2-view-toggle child.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
key | string | — | Key of the switch in value.show. |
label | string | — | Text shown next to the switch. Defaults to the element's text, then to key. |
checked | boolean | false | State used while value.show has no entry for this key. |