Quaff

QList

Lists arrange related items in vertical rows. Combine text, icons, and actions, with optional selection, separators, and compact spacing.

At the bar

Counter
A seat by the bar
Window seats
A quiet corner for two
Terrace
Fresh air and room for four
info QList API Source
interface QListProps extends HTMLAttributes<HTMLElement>
activeClass
?: string = undefined
Class string to apply when the component (or its associated route) is active. `activeClass` on component groups (e.g. `QList`, `QTabs` etc.) will apply to active components they contain. `activeClass` on individual components (e.g. `QItem`, `QTab` etc.) will overwrite `activeClass` from their containing group.
activeStyle
?: string = undefined
Styles to add when the component (or its associated route) is active. `activeStyle` on component groups (e.g. `QList`, `QTabs` etc.) will apply to active components they contain. `activeStyle` on individual components (e.g. `QItem`, `QTab` etc.) will overwrite `activeStyle` from their containing group.
bordered
?: boolean = false
Adds a border around the list.
dense
?: boolean = false
Makes all the items in the list more compact.
expressive
?: boolean = undefined
Applies Material 3 Expressive list styling. When omitted, inherits the `Quaff.init()` setting (false by default). Inside QMenu, uses the menu styling instead. Set true or false to override it.
noRound
?: boolean = false
Removes the rounded borders when bordered is true.
padding
?: boolean = false
Adds padding to the list container.
preserveTabOrder
?: boolean = false
Preserves child elements' tab order and disables the list's arrow-key navigation.
segmented
?: boolean = false
Separates expressive list items with a small gap.
selection
?: QListSelection = undefined
Enables single- or multiple-selection list semantics. Selection state is controlled with QItem's active prop.
separator
?: boolean = false
Adds separators between list items.
separatorOptions
?: Omit<QSeparatorHorizontalProps, "vertical"> = {}
Options for the separators. These will be applied to all separators in the list.
tag
?: string = "div"
HTML tag to be used for the list container.
info QItem API Source
interface QItemProps extends HTMLAttributes<HTMLElement>
active
?: boolean = undefined
Overrides the active state. When omitted, follows the current route.
activeClass
?: string = undefined
Class string to apply when the component (or its associated route) is active. `activeClass` on component groups (e.g. `QList`, `QTabs` etc.) will apply to active components they contain. `activeClass` on individual components (e.g. `QItem`, `QTab` etc.) will overwrite `activeClass` from their containing group.
activeStyle
?: string = undefined
Styles to add when the component (or its associated route) is active. `activeStyle` on component groups (e.g. `QList`, `QTabs` etc.) will apply to active components they contain. `activeStyle` on individual components (e.g. `QItem`, `QTab` etc.) will overwrite `activeStyle` from their containing group.
clickable
?: boolean = false
Makes the item clickable and adds hover effects.
dense
?: boolean = false
Makes the item more compact.
disabled
?: boolean = false
Puts the component into a disabled state, which prevents user interaction.
draggable
?: boolean = undefined
Enables native dragging and applies the dragged visual state while dragging.
dragged
?: boolean = false
Applies the dragged visual state.
href
?: string = undefined
Makes the component navigational, typically used for links to set the URL or route it should navigate to.
noRipple
?: boolean = false
Disables the ripple effect when clicking the item.
noSeparator
?: boolean = false
Prevents the separator supplied by the containing QList from rendering before this item.
replace
?: boolean = false
Replaces the current entry in the browser's history rather than adding a new one. This is the same as setting the `data-sveltekit-replacestate` attribute to "true".
tag
?: string = "div"
HTML tag to be used for the list item.
target
?: HTMLAnchorAttributes["target"] = undefined
Target attribute for anchor tags when using router links.
to
?: string = undefined
Makes the component navigational, typically used for links to set the URL or route it should navigate to. As it is the same as href, it is recommended to use href instead.
info QItemSection API Source
interface QItemSectionProps extends HTMLAttributes<HTMLElement>
action
?: boolean = false
Renders the content section as the primary button in a multi-action list item.
dragHandle
?: boolean = false
Marks this section as a pointer drag handle.
type
?: QItemSectionTypes = "content"
Type of the section, determines its layout and styling.

Usage

Basic List
QList contains rows of QItem; each QItemSection holds the content of a row. Start with a single section for a simple text list, then add icons, supporting text or actions as needed.
Table service
Step-free entrance
Outdoor seating

Lists and items render as div elements by default; this example adds list and listitem roles. Use tag for other HTML elements, such as ul and li.

Appearance
Compare one-, two- and three-line rows. segmented adds gaps between expressive items; dense reduces row height. This preview keeps borders, padding and separators in baseline mode: turn off Expressive to try them.
Expressive
Segmented
Dense
Doors open
17:00
Live piano
A short set by the window
18:00
Evening quiz
Teams of up to four
Sign up at the counter
19:30

An individual QItem dense also opts into compact spacing; it cannot undo dense on its list. expressive inherits Quaff.init({ expressive: true }) when omitted; set expressive={false} to use standard styling. Inside QMenu, lists use menu styling unless expressive is explicitly set.

Multiple Actions
For one action on the whole row, use QItem clickable with an onclick handler. For independent actions, keep the item non-clickable and put action on the content section to render a native button. Its leading snippet includes the avatar in the same target.
Show save actions

Last primary action: None. Saved areas: 1.

By default the list has one Tab stop. Arrow keys cycle through available row actions; Tab leaves the list. Keep a conditional action's entire QItemSection inside the conditional block so keyboard navigation updates when it is added or removed.

Selection
Choose between native form controls and selectable rows. QRadio and QCheckbox use real inputs; preserveTabOrder keeps their keyboard behavior. Turn off the controls to try selection="single" and selection="multiple" listboxes with clickable options.
Use checkbox and radio controls
Click anywhere in the row
Disable item ripples

Booking time

Table requests

Booking time: 19:00. Requests selected: 1 of 3.

The selection is kept when switching modes. In listbox mode, arrow keys move focus; Enter or Space selects an option. The application updates active to reflect its state. In form mode, radio arrow keys select a time and Space toggles a checkbox. Disabled choices are skipped. Enable “Click anywhere in the row” to extend the native controls' click targets to the row edges.

Controls in Rows
Combine a setting's description with a trailing control. Use preserveTabOrder to keep normal Tab navigation and text editing. toggle holds a control without shrinking; side accommodates content at its natural width.
Booking reminder
Receive a reminder before your booking
Booking details
Reordering
Native draggable enables dragging the whole row and applies its dragged appearance. dragHandle marks the grip visually; it does not restrict where a native drag starts. The application handles the order. Drag a task before another or use its button to move it to first.
  1. Clear the counter
    Position 1
  2. Refill the water station
    Position 2
  3. Set out the menus
    Position 3

Current task order.

The keyboard action keeps focus on the moved button and announces its new position. Custom pointer or touch implementations can set dragged directly.

Images and Supporting Text
Keep related rows aligned by using the same section types. thumbnail sizes square images; avatar holds an avatar, as in the preview. The content section accepts a headline and supporting snippets line1 through line3. trailingText keeps short metadata separate.
Getting the ice right
Keep a fresh scoop ready for service.
A quick guide for the counter
3 min
Citrus finishing touches
Add fresh slices just before serving.
Simple details for the menu
5 min

Use icon for a leading symbol and trailingIcon for a trailing symbol. video sizes a video preview to 114 × 64 pixels. The sample photos are local docs assets; replace their src paths with your own images.

Accessibility

Give interactive lists a clear accessible name. For static content, use list and list-item roles or semantic ul/li tags. Hide decorative icons from assistive technology, and label every icon-only action.

By default, Tab enters and leaves an interactive list; arrow keys move between its actions. Selection lists use listbox/option semantics and expose active as the selected state. Keep their selection indicators decorative.

For form controls, omit selection and enable preserveTabOrder. Give checkboxes and radios visible labels, and related radios a shared name. Keep inputs as the only keyboard targets; do not also make their rows clickable. Provide a keyboard alternative for drag operations, as in the reordering example.

Privacy Policy