# Pop-Up Button

A dropdown button that opens a menu of selectable items.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).



<ComponentPreview name="pop-up-button/Basic" />

## Import [#import]

```rust
use maccn::{MacPopUpButton, MacPopUpButtonItem};
```

## Usage [#usage]

```rust
MacPopUpButton::new("format")
    .placeholder("Choose format")
    .items(vec![
        MacPopUpButtonItem::new("PDF"),
        MacPopUpButtonItem::new("PNG"),
        MacPopUpButtonItem::separator(),
        MacPopUpButtonItem::new("Custom").disabled(true),
    ])
    .selected(Some(0));
```

## Sizes [#sizes]

<ComponentPreview name="pop-up-button/Sizes" />

```rust
use gpui::div;
use maccn::{MacControlSize, MacPopUpButton};

div()
    .flex()
    .items_center()
    .gap_2()
    .child(
        MacPopUpButton::new("popup-xl")
            .size(MacControlSize::ExtraLarge)
            .placeholder("Extra Large"),
    )
    .child(
        MacPopUpButton::new("popup-l")
            .size(MacControlSize::Large)
            .placeholder("Large"),
    )
    .child(MacPopUpButton::new("popup-r").placeholder("Regular"))
    .child(
        MacPopUpButton::new("popup-s")
            .size(MacControlSize::Small)
            .placeholder("Small"),
    )
    .child(
        MacPopUpButton::new("popup-m")
            .size(MacControlSize::Mini)
            .placeholder("Mini"),
    )
```

## States [#states]

<ComponentPreview name="pop-up-button/States" />

```rust
use gpui::div;
use maccn::{MacPopUpButton, MacPopUpButtonItem};

div()
    .flex()
    .flex_col()
    .gap_2()
    .child(
        MacPopUpButton::new("popup-d")
            .disabled(true)
            .placeholder("Disabled"),
    )
    .child(
        MacPopUpButton::new("popup-item-d")
            .placeholder("With disabled item")
            .items(vec![
                MacPopUpButtonItem::new("Red"),
                MacPopUpButtonItem::new("Green").disabled(true),
                MacPopUpButtonItem::new("Blue"),
            ]),
    )
```

## API [#api]

### MacPopUpButton Props [#macpopupbutton-props]

| Prop          | Type             | Default    |
| ------------- | ---------------- | ---------- |
| `size`        | `MacControlSize` | `Regular`  |
| `selected`    | `Option<usize>`  | `None`     |
| `placeholder` | `SharedString`   | `"Select"` |
| `disabled`    | `bool`           | `false`    |

### MacPopUpButton Methods [#macpopupbutton-methods]

| Method                                                | Description            |
| ----------------------------------------------------- | ---------------------- |
| `item(MacPopUpButtonItem)`                            | Appends a single item. |
| `items(impl IntoIterator<Item = MacPopUpButtonItem>)` | Replaces all items.    |

### MacPopUpButtonItem [#macpopupbuttonitem]

| Method                                          | Description                       |
| ----------------------------------------------- | --------------------------------- |
| `new(label: impl Into<SharedString>)`           | Creates a selectable item.        |
| `disabled(bool)`                                | Disables the item.                |
| `on_select(handler: Fn(&mut Window, &mut App))` | Called when the item is selected. |
| `separator()`                                   | Creates a menu separator.         |