# PrimaryActions

**Category:** Features/Actions/PrimaryActions

## Design

### Description

The `PrimaryActions` component displays a primary action button in a collection page header. Each action can be a single button or a button with a dropdown menu that shows additional actions.


```tsx
import { PrimaryActions } from '@wix/patterns';
```

### Basic primary action button

Adds a primary action button with the default label and add icon.

```tsx
import React from 'react';
import { PrimaryActions } from '@wix/patterns';
import { CollectionPage } from '@wix/patterns/page';

function Basic() {
  return (
    <CollectionPage height="400px">
      <CollectionPage.Header
        title={{ text: 'Page' }}
        primaryAction={
          <PrimaryActions onClick={() => console.log('I do something')} />
        }
      />
      <CollectionPage.Content>Content</CollectionPage.Content>
    </CollectionPage>
  );
}
```

### Customized primary action button

Override the default label and icon by providing your own `label` and `prefixIcon` props.

```tsx
import React from 'react';
import { PrimaryActions } from '@wix/patterns';
import { CollectionPage } from '@wix/patterns/page';
import { Duplicate } from '@wix/wix-ui-icons-common';

function Overrides() {
  return (
    <CollectionPage height="400px">
      <CollectionPage.Header
        title={{ text: 'Page' }}
        primaryAction={
          <PrimaryActions
            label="Duplicate"
            prefixIcon={<Duplicate />}
            onClick={() => console.log('I am duplicating')}
          />
        }
      />
      <CollectionPage.Content>Content</CollectionPage.Content>
    </CollectionPage>
  );
}
```

### Multiple actions with a dropdown

Provide multiple actions using the `subItems` prop. The button displays with a dropdown menu that shows the additional actions when clicked.

```tsx
import React from 'react';
import { PrimaryActions } from '@wix/patterns';
import { CollectionPage } from '@wix/patterns/page';
import { Duplicate, Edit } from '@wix/wix-ui-icons-common';

function WithSubitems() {
  return (
    <CollectionPage height="400px">
      <CollectionPage.Header
        title={{ text: 'Page' }}
        primaryAction={
          <PrimaryActions
            label="Duplicate"
            prefixIcon={<Duplicate />}
            subItems={[
              {
                label: 'Edit',
                prefixIcon: <Edit />,
                onClick: () => console.log('Edit'),
              },
              {
                label: 'delete',
                onClick: () => console.log('Edit'),
                disabled: true,
                tooltip: 'Disabled',
              },
            ]}
          />
        }
      />
      <CollectionPage.Content>Content</CollectionPage.Content>
    </CollectionPage>
  );
}
```

### Grouped actions with dividers

Group actions by providing `subItems` as nested arrays. Each array creates a group, and dividers appear between groups in the dropdown menu.

```tsx
import React from 'react';
import { PrimaryActions } from '@wix/patterns';
import { CollectionPage } from '@wix/patterns/page';
import { Duplicate, Edit } from '@wix/wix-ui-icons-common';

function WithSubitems() {
  return (
    <CollectionPage height="400px">
      <CollectionPage.Header
        title={{ text: 'Page' }}
        primaryAction={
          <PrimaryActions
            label="Duplicate"
            prefixIcon={<Duplicate />}
            subItems={[
              [
                {
                  label: 'Edit',
                  prefixIcon: <Edit />,
                  onClick: () => console.log('Edit'),
                },
              ],
              [
                {
                  label: 'delete',
                  onClick: () => console.log('Edit'),
                  disabled: true,
                  tooltip: 'Disabled',
                },
              ],
            ]}
          />
        }
      />
      <CollectionPage.Content>Content</CollectionPage.Content>
    </CollectionPage>
  );
}
```

## API

### Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `onClick` | `any` | No | - | A callback that runs each time the button is clicked. |
| `label` | `string` | No | - | Button label. |
| `subtitle` | `string` | No | - | Subtitle text displayed for buttons in the popover menu. |
| `prefixIcon` | `IconElement` | No | - | An icon displayed before the button label. |
| `tooltip` | `string` | No | - | An optional tooltip when the popover is disabled. |
| `disabled` | `boolean` | No | - | An optional disabled flag. |
| `dataHook` | `string` | No | - | A data-hook for the button. |
| `biName` | `string` | No | - | A unique name for a `cairoPageCtaClicked` BI event. |
| `biAdditionalInfo` | `string` | No | - | Additional info for a `cairoPageCtaClicked` BI event. |
| `subItems` | `ActionSubitem[] \| ActionSubitem[][]` | No | - | Action items to render in a popover menu. Use nested arrays to group actions. A divider is added between each group. \| [ActionSubitem[][]](./?path=/story/common-types--actionsubitem) |
| `popoverMenuProps` | `Partial<PopoverMenuProps>` | No | - | Custom [`PopoverMenuProps`](https://www.docs.wixdesignsystem.com/?path=/story/components-overlays--popovermenu) to pass to the sub-items popover menu. |
| `ref` | `Ref<HTMLButtonElement>` | No | - | Optional ref to the underlying button element (for focus restoration, etc.). |