# LabelItem and CheckLabelItem

> Ready-made list item cards — label only (SINGLE) or checkbox + label (MULTIPLE).

Source: https://crossfly.dev/docs/ui/widgets/list-items — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# LabelItem and CheckLabelItem

`LabelItem` and `CheckLabelItem` are ready-made list item "cards", in the `dev.crossfly.ui.listitem` package. Both extend `Component` and are used internally by [`ListView`](/docs/ui/widgets/listview):

- **`LabelItem`** — a single `Label` with line wrapping. Used in `SINGLE` mode.
- **`CheckLabelItem`** — an `Option` (check) + `Label`. Used in `MULTIPLE` mode.

You normally do **not** instantiate them directly — the `ListView` creates the right type based on the `ItemType`. Use them when building a list by hand and you want the same card appearance/behavior.

> 🟡 · **Package:** `dev.crossfly.ui.listitem` · **Extend:** `Component` · **Style:** `ComponentStyle` (card) + `LabelStyle` (label)

## When to use
- Building a list manually (outside `ListView`) while reusing the standard card look.
- A standalone clickable item with an appearance consistent with the framework's lists.

## When NOT to use
- Ready-made selection list → let the [`ListView`](/docs/ui/widgets/listview) create the items for you.
- Rich row with image/multiple fields → build your own `Component` (or use the `ListView`'s `itemFactory`).

## Appearance
Card with the selection theme's background/border (`selectionCardBackColor`/`selectionCardBorderColor`), `pressable`, with default gaps. `LabelItem` shows the text aligned START/CENTER; `CheckLabelItem` places the check on the left (automatic width) and the label taking up 90%.

## Complete example (copy, paste and run)
```java
package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.listitem.*;   // LabelItem, CheckLabelItem

/** Runnable main screen. Point the launcher (classname) and run: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      // List built by hand reusing the standard card visual.
      Component lista = new Component();
      lista.setLayout(new GridLayout(Position.CENTER, Position.START));
      lista.setScrollable(ScrollDirection.VERTICAL);

      String[] linhas = {"Alpha", "Beta", "Gamma"};
      for (int i = 0; i < linhas.length; i++) {
         LabelItem item = new LabelItem(linhas[i], i);
         final int idx = i;
         item.onAction(e -> System.out.println("selecionou " + idx));
         lista.add(.95f, item);
      }

      CheckLabelItem termos = new CheckLabelItem("Aceito os termos", linhas.length);
      termos.onAction(e -> { termos.toggle(); System.out.println(termos.isChecked()); });
      lista.add(.95f, termos);

      add(LAY_FILL, lista);   // lists use LAY_FILL (they absorb the height)
   }
}
```

> The snippets below show **only the core** (what goes inside `onShow()`). To run them, place them in the `MainWindow` skeleton above.

## Basic usage
```java
// LabelItem — clickable single-label item
LabelItem item = new LabelItem("Linha", 0);
item.onAction(e -> System.out.println("clicou " + item.index));
layout.add(.95f, item);

// CheckLabelItem — item with a checkbox
CheckLabelItem c = new CheckLabelItem("Aceito os termos", 0);
c.onAction(e -> { c.toggle(); System.out.println(c.isChecked()); });
layout.add(.95f, c);
```

### LabelItem
| Constructor | Description |
|---|---|
| `LabelItem(String text, int index)` | Default styles |
| `LabelItem(String text, int index, ComponentStyle cardStyle, LabelStyle labelStyle)` | Custom styles |

### CheckLabelItem
| Constructor | Description |
|---|---|
| `CheckLabelItem(String text, int index)` | Default style |
| `CheckLabelItem(String text, int index, ComponentStyle cardStyle)` | Custom card style |

The `text` and `index` fields are `public final`.

## Properties and customization
| Member | Class | What it does |
|---|---|---|
| `text` (final) | both | Item text |
| `index` (final) | both | Item index in the list |
| `getAutoHeight()` | both | Preferred height (label/check + ingap) |
| `isChecked()` | `CheckLabelItem` | Current check state |
| `setChecked(boolean)` | `CheckLabelItem` | Sets the state |
| `toggle()` | `CheckLabelItem` | Toggles the state |
| `getCheck()` | `CheckLabelItem` | Access to the internal `Option` |
| `defaultItemStyle()` (static) | both | Reusable card style (selection card, `pressable`) |
| `defaultLabelStyle()` (static) | `LabelItem` | Reusable label style |

## Callbacks and events
| Callback | When it fires |
|---|---|
| `onAction(Action)` | On tapping the card (inherited from `Component`) |

In `CheckLabelItem`, the tap does **not** toggle the check on its own — call `toggle()` in your callback (this is what `ListView` does internally).

## States
- **pressed** — both are `pressable` by default (tap feedback).
- **checked** — only `CheckLabelItem`: controlled by `setChecked`/`toggle`, queryable with `isChecked`.

### Manual list reusing the card look
```java
Component lista = new Component();
lista.setLayout(new GridLayout(Position.CENTER, Position.START));
lista.setScrollable(ScrollDirection.VERTICAL);
String[] linhas = {"Alpha", "Beta", "Gamma"};
for (int i = 0; i < linhas.length; i++) {
   LabelItem item = new LabelItem(linhas[i], i);
   final int idx = i;
   item.onAction(e -> System.out.println("selecionou " + idx));
   lista.add(.95f, item);
}
layout.add(LAY_FILL, lista);
```

### CheckLabelItem with a custom card
```java
ComponentStyle card = CheckLabelItem.defaultItemStyle()
   .copy()
   .backColor(0xFFF5F5F5);
CheckLabelItem opt = new CheckLabelItem("Receber notificações", 0, card);
opt.setChecked(true);
opt.onAction(e -> { opt.toggle(); });
layout.add(.95f, opt);
```

## Best practices
- Reuse `defaultItemStyle()` / `defaultLabelStyle()` (with `.copy()`) to keep visual cohesion with the framework's lists.
- Add the items with `.95f` width in a `GridLayout(CENTER, START)` to reproduce the `ListView` spacing.

## Common mistakes
- **Expecting `CheckLabelItem` to toggle the check automatically on tap** — call `toggle()` in `onAction`.
- **Instantiating these items when you already use `ListView`** — the `ListView` already creates the correct type via the `ItemType`.

## See also
- Area guide: [`ui/`](/docs/ui) · Recipes: [`cookbook/`](/docs/cookbook)
- Related components: [`ListView`](/docs/ui/widgets/listview) · [`ListViewWindow`](/docs/ui/widgets/listviewwindow)