PlList

A stack of rows. The list is a sheet and the rows are what is on it, so size and density belong to the stack and a row inherits them.

React

import { PlList, PlListItem } from 'plass-ui';

<PlList>
  <PlListItem description="Three unread" onClick={open}>
    Inbox
  </PlListItem>
  <PlListItem description="One saved">Drafts</PlListItem>
</PlList>;

import 'package:plass_ui/plass_ui.dart';

PlList(
  children: <Widget>[
    PlListItem(description: const Text('Three unread'), onPressed: open, child: const Text('Inbox')),
    const PlListItem(description: Text('One saved'), child: Text('Drafts')),
  ],
);

Props

Prop	Type	Default	Description
variantshared	'solid' | 'glass' | 'ghost'	'glass'	What the sheet is made of. As on any container it is never dyed. ghost is the one to reach for inside a card: the card is already a sheet, and a second bordered rectangle in it is a second rectangle
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Type scale and padding of the rows. A property of the stack, not of any one row in it
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. Arbitrary colour values are not accepted
densityshared	'default' | 'compact'	'default'	Padding only — never the height, never the type scale
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. 0 means no shadow at all
dividers	boolean	false	Separates the rows with a hairline instead of with space. It changes more than it sounds like: the rules have to reach both edges, so the sheet gives up its padding and the rows give up their corners
render	useRender.RenderProp	—	Renders something other than a ul — render={<ol />} for a list where the order is the point
children	ReactNode	—	The PlListItems

Prop	Type	Default	Description
children *	List<Widget>	—	The rows
variantshared	PlassVariant	PlassVariant.glass	What the sheet is made of. As on any container it is never dyed. ghost is the one to reach for inside a card: the card is already a sheet, and a second bordered rectangle in it is a second rectangle
sizeshared	PlassSize	PlassSize.md	Type scale and padding of the rows. A property of the stack, not of any one row in it
colorshared	PlassColor	PlassColor.primary	Semantic colour role. Arbitrary colour values are not accepted
densityshared	PlassDensity	PlassDensity.standard	Padding only — never the height, never the type scale
elevationshared	int	0	Drop shadow depth. 0 means no shadow at all
dividers	bool	false	Separates the rows with a hairline instead of with space. It changes more than it sounds like: the rules have to reach both edges, so the sheet gives up its padding and the rows give up their corners

Every native <ul> attribute passes straight through. color is excluded from the pass-through because it is a Plass prop here.

PlListItem

Prop	Type	Default	Description
onClick	(event: MouseEvent) => void	—	Passing it is what turns the row into a real button. It lands on that button rather than on the li
href	string	—	Renders the row as a link
startIcon	ReactNode	—	Content before the label — an icon, an avatar, a status dot
endIcon	ReactNode	—	Content after the label, inside the pressable area
description	ReactNode	—	A second line under the label, one step down the type scale and muted
action	ReactNode	—	A control pinned to the end of the row. Deliberately **outside** the pressable area: a row that both navigates and holds a toggle has two things to press, and a button inside a button is markup the browser rewrites on parse
selected	boolean	false	Marks the row as the chosen one — the open page, the current filter. aria-current="page" on a link, "true" on a button
disabledshared	boolean	false	Unavailable. The light goes out and it stops being pressable
children	ReactNode	—	The label

Prop	Type	Default	Description
child	Widget?	—	The label
onPressed	VoidCallback?	—	Passing it is what turns the row into a real button. It lands on that button rather than on the li
startIcon	Widget?	—	Content before the label — an icon, an avatar, a status dot
endIcon	Widget?	—	Content after the label, inside the pressable area
description	Widget?	—	A second line under the label, one step down the type scale and muted
action	Widget?	—	A control pinned to the end of the row. Deliberately **outside** the pressable area: a row that both navigates and holds a toggle has two things to press, and a button inside a button is markup the browser rewrites on parse
selected	bool	false	Marks the row as the chosen one — the open page, the current filter. aria-current="page" on a link, "true" on a button
disabledshared	bool	false	Unavailable. The light goes out and it stops being pressable

Every native <li> attribute passes straight through, onto the <li> rather than onto the button or link inside it. size, density and dividers are inherited from the PlList around it, a row that disagreed with its neighbours about any of them is a list with a hole in it.

size, density, color and dividers are inherited from the PlList around it, through an InheritedWidget, a row that disagreed with its neighbours about any of them is a list with a hole in it. Which is also why a PlListItem outside a PlList asserts rather than picking defaults: a row is a row of something.

What the shared axes (variant size color density elevation) mean across the library is in prop conventions.

Examples

A row

The shell is always an <li>. What changes is what is inside it: a plain run of content, or (when onClick or href is given) a real <button> or <a> wrapping that content.

action sits outside that pressable area on purpose. A row that both navigates and holds a toggle has two things to press, and a <button> inside a <button> is markup the browser rewrites on parse.

A row with onPressed is a focus stop announced as a button; one without adds no role and takes none.

action sits outside that pressable area on purpose. A row that both navigates and holds a toggle has two things to press, and a nested gesture recogniser would take one tap twice.

React

import { PlButton, PlList, PlListItem } from 'plass-ui';

function BellIcon() {
  return (
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.6">
      <path d="M18 8a6 6 0 1 0-12 0c0 6-2 7-2 7h16s-2-1-2-7" strokeLinejoin="round" />
      <path d="M13.7 20a2 2 0 0 1-3.4 0" strokeLinecap="round" />
    </svg>
  );
}

export default function ListRows() {
  return (
    <PlList className="w-full max-w-md" dividers>
      <PlListItem>Not pressable</PlListItem>
      <PlListItem onClick={() => {}}>A real button</PlListItem>
      <PlListItem href="#list">A real link</PlListItem>
      <PlListItem selected href="#list">
        The chosen one
      </PlListItem>
      <PlListItem disabled onClick={() => {}}>
        Unavailable
      </PlListItem>
      <PlListItem
        startIcon={<BellIcon />}
        description="Outside the pressable area, on purpose"
        onClick={() => {}}
        action={
          <PlButton size="xs" variant="ghost" color="secondary">
            Mute
          </PlButton>
        }
      >
        With an action
      </PlListItem>
    </PlList>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';
import 'package:plass_ui_example/demos/glyphs.dart';

class ListRows extends StatelessWidget {
  const ListRows({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 448,
      child: PlList(
        dividers: true,
        children: <Widget>[
          const PlListItem(child: Text('Not pressable')),
          PlListItem(onPressed: () {}, child: const Text('A real focus stop')),
          PlListItem(selected: true, onPressed: () {}, child: const Text('The chosen one')),
          PlListItem(disabled: true, onPressed: () {}, child: const Text('Unavailable')),
          PlListItem(
            startIcon: const BellGlyph(),
            description: const Text('Outside the pressable area, on purpose'),
            onPressed: () {},
            action: PlButton(
              size: PlassSize.xs,
              variant: PlassVariant.ghost,
              color: PlassColor.secondary,
              onPressed: () {},
              child: const Text('Mute'),
            ),
            child: const Text('With an action'),
          ),
        ],
      ),
    );
  }
}

dividers

With dividers the rules have to reach both edges of the sheet, so the list gives up its inner padding and the rows give up their rounded corners. A row cannot be a floating tile and a ruled line at the same time.

React

import { PlList, PlListItem } from 'plass-ui';

export default function ListDividers() {
  return (
    <div className="flex w-full max-w-md flex-col gap-5">
      <PlList>
        <PlListItem onClick={() => {}}>Tiles, with space between them</PlListItem>
        <PlListItem onClick={() => {}}>The sheet keeps its padding</PlListItem>
      </PlList>

      <PlList dividers>
        <PlListItem onClick={() => {}}>Ruled lines, edge to edge</PlListItem>
        <PlListItem onClick={() => {}}>The sheet gives its padding up</PlListItem>
      </PlList>
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class ListDividers extends StatelessWidget {
  const ListDividers({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 448,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        mainAxisSize: MainAxisSize.min,
        spacing: 20,
        children: <Widget>[
          PlList(
            children: <Widget>[
              PlListItem(onPressed: () {}, child: const Text('Tiles, with space between them')),
              PlListItem(onPressed: () {}, child: const Text('The sheet keeps its padding')),
            ],
          ),
          PlList(
            dividers: true,
            children: <Widget>[
              PlListItem(onPressed: () {}, child: const Text('Ruled lines, edge to edge')),
              PlListItem(onPressed: () {}, child: const Text('The sheet gives its padding up')),
            ],
          ),
        ],
      ),
    );
  }
}

variant

The sheet is never dyed, exactly as on a PlCard. A list holds other people's content, and that content arrives with its own colours.

ghost is the one to use inside a card: the card is already a sheet, and a second bordered rectangle inside it is a second rectangle.

React

import { PlList, PlListItem } from 'plass-ui';

export default function ListVariants() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      {(['solid', 'glass', 'ghost'] as const).map((variant) => (
        <PlList key={variant} variant={variant} size="sm">
          <PlListItem onClick={() => {}}>{variant}</PlListItem>
          <PlListItem onClick={() => {}}>A second row</PlListItem>
        </PlList>
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class ListVariants extends StatelessWidget {
  const ListVariants({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 448,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        mainAxisSize: MainAxisSize.min,
        spacing: 16,
        children: <Widget>[
          for (final variant in PlassVariant.values)
            PlList(
              variant: variant,
              size: PlassSize.sm,
              children: <Widget>[
                PlListItem(onPressed: () {}, child: Text(variant.name)),
                PlListItem(onPressed: () {}, child: const Text('A second row')),
              ],
            ),
        ],
      ),
    );
  }
}

size

React

import { PlList, PlListItem } from 'plass-ui';

export default function ListSizes() {
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      {(['xs', 'sm', 'md', 'lg', 'xl'] as const).map((size) => (
        <PlList key={size} size={size}>
          <PlListItem description="and a description" onClick={() => {}}>
            {size}
          </PlListItem>
        </PlList>
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class ListSizes extends StatelessWidget {
  const ListSizes({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 448,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        mainAxisSize: MainAxisSize.min,
        spacing: 16,
        children: <Widget>[
          for (final size in PlassSize.values)
            PlList(
              size: size,
              children: <Widget>[
                PlListItem(
                  description: const Text('and a description'),
                  onPressed: () {},
                  child: Text(size.name),
                ),
              ],
            ),
        ],
      ),
    );
  }
}

Accessibility

• There is no Base UI primitive under this on purpose. A list is not a composite widget. It has no roving focus, no selection model, no keyboard contract of its own. Reaching for a menu or a listbox primitive would hand a plain list of links the semantics of a menu.
• role="list" is written out because Tailwind's reset takes the bullets off every <ul>, and Safari takes the list semantics off with them.
• A chosen link carries aria-current="page" and a chosen button aria-current="true". The first says "this is the page you are on", the second "this is the chosen one of these". aria-pressed would be a third thing, a toggle, and a selected row is not a toggle.
• A row with neither onClick nor href adds no role and takes no tab stop. An inert <div> with a click handler on it is invisible to a keyboard.
• Give the control in action its own accessible name. It is a separate tab stop from the row, which is the point of it being there.

• A list is not a composite widget (it has no roving focus, no selection model and no keyboard contract of its own), so it adds no role beyond grouping its rows, and each row speaks for itself.
• A chosen row reports that it is selected. It is not a toggle, and it does not claim to be one.
• A row with no onPressed adds no role and takes no focus stop.
• Give the widget in action its own name. It is a separate focus stop from the row, which is the point of it being there.
• A row's focus ring turns inward when the list is ruled, so it is not sliced off at the sheet's clipped edge.

Differences from the React build

React	Flutter	Why
onClick / href	onPressed	Flutter has no link element, so a row that navigates calls your router from onPressed.
<ul> / <li> and role="list"	a grouped semantics node	There are no bullets to reset and no list semantics for a reset to take away.
aria-current="page" vs "true"	selected	Flutter's semantics tree has one selection flag and no page-vs-option distinction.
a React context	an InheritedWidget	The same idea in Flutter's words, for the same reason: cloning children stops reaching a row the moment a caller wraps one.
render	—	Flutter has no polymorphic element.
children on a row	child	Flutter's name.