> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: AddItem Component

## Article: AddItem Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/actions/add-item-component.md

## Article Content:

# AddItem

_Components/Actions_

Interactive docs page: <https://wix-pages.com/design-system-documentation/#/component/additem>

## Overview

```jsx
<Box align="center">
  <Box width="30%">
    <AddItem>Add Item</AddItem>
  </Box>
</Box>;
```

Add item component allows users to add a new item to an existing list.

### Do

- Use it to add a new item to the list.
- Use it together with `<FileUpload/>` mechanism to add a new file to a list.

### Don't

- Don't use it for standard actions. Use `<Button/>` or `<TextButton/>` instead.

### Feature examples

#### Size

Control the size of a component with `size` prop:

- `large` - use when item height is >212 px.
- `medium` - use when item height is between 162 px and 212 px.
- `small` - use when item height is between 120 px and 162 px.
- `tiny` (default) - use when item height is between 48 px and 120 px.

`size` prop affects component's padding and icon size. Its height and width also depend on a parent container.

Minimum height of a component is:

- 48 px for `dashes`,
- 42 px for `plain`, and
- 81×81 px for `image` themes.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AddItem size="large">Large</AddItem>
  <AddItem size="medium">Medium</AddItem>
  <AddItem size="small">Small</AddItem>
  <AddItem size="tiny">Tiny</AddItem>
</StorybookComponents.Stack>;
```

#### Theme

Control the style of a component with `theme` prop:

- `dashes` (default) - use it outside of a card, in a table or a list that contains images.
- `plain` - use for in-card lists and tables that mainly consist of text.
- `filled` - use for small in-card items, when a prominent call to action is needed.
- `image` - use to add images inside a card.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AddItem theme="dashes">Dashes</AddItem>
  <AddItem theme="plain">Plain</AddItem>
  <AddItem theme="filled">Filled</AddItem>
  <AddItem theme="image">Image</AddItem>
</StorybookComponents.Stack>;
```

#### Alignment

Control content alignment with `alignItems` prop:

- `left`
- `center` (default)
- `right`

Use `left` alignment with a `plain` component theme to maintain visual consistency with a remaining list inside a card.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AddItem theme="plain" alignItems="left">
    Left
  </AddItem>
  <AddItem theme="plain" alignItems="center">
    Center
  </AddItem>
  <AddItem theme="plain" alignItems="right">
    Right
  </AddItem>
</StorybookComponents.Stack>;
```

#### Padding

Control whether a component has padding with `removePadding` prop.

Use it in special cases only, when component is used in dense and narrow layouts.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AddItem>Default</AddItem>
  <AddItem removePadding>No padding</AddItem>
</StorybookComponents.Stack>;
```

#### Border radius

Control the border radius of a component with `borderRadius` prop.

By default, component has a corner radius of 8 px. Change it in custom scenarios, for example, when user needs to add a round avatar photo.

```jsx
<StorybookComponents.Stack width="min-content" height="100px">
  <AddItem borderRadius="8px" />
  <AddItem borderRadius="100%" />
</StorybookComponents.Stack>;
```

#### Title

Emphasize action with a `title`.

If no title is shown, display it in a tooltip on item hover with `tooltipContent` prop.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AddItem>Title</AddItem>
  <AddItem tooltipContent="Title"></AddItem>
</StorybookComponents.Stack>;
```

#### Subtitle

Add a description below the title using `subtitle` prop.

Use it to explain item details, such as a supported file format of a maximum allowed file size.

```jsx
<AddItem subtitle="Subtitle">Title</AddItem>;
```

#### Subtitle placement

Control where the subtitle appears with `subtitlePlacement` prop:

- `bottom` (default) - shows the subtitle below the title.
- `top` - shows the subtitle above the title. Use it when the description explains the action, and the title reads as the action itself.

```jsx
<StorybookComponents.Stack>
  <Box height="162px" width="50%">
    <AddItem size="small" subtitle="Subtitle">
      Title
    </AddItem>
  </Box>
  <Box height="162px" width="50%">
    <AddItem size="small" subtitle="Subtitle" subtitlePlacement="top">
      Title
    </AddItem>
  </Box>
</StorybookComponents.Stack>;
```

#### Aligned items

Line up the text of items placed side by side by giving every item an icon of the same height.

An illustration passed as a source string is always rendered at a fixed size. Wrap a custom icon in a box of that size, for example 60×60 px for a `small` item.

```jsx
<StorybookComponents.Stack>
  <Box height="162px" width="50%">
    <AddItem
      size="small"
      icon="running_man.png"
      subtitle="Add images or videos of your product"
      subtitlePlacement="top"
    >
      Upload
    </AddItem>
  </Box>
  <Box height="162px" width="50%">
    <AddItem
      size="small"
      icon={
        <Box width="60px" height="60px" align="center" verticalAlign="middle">
          <Icons.AI />
        </Box>
      }
      subtitle="Turn your photos into professional product shots"
      subtitlePlacement="top"
    >
      Generate
    </AddItem>
  </Box>
</StorybookComponents.Stack>;
```

#### Icon

Control a '+' icon visibility with `showIcon` prop. The icon is always shown by default.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <AddItem>Default</AddItem>
  <AddItem showIcon={false}>No icon</AddItem>
</StorybookComponents.Stack>;
```

#### Custom icon or illustration

Override a default '+' icon with a custom icon or illustration by passing it to `icon` prop.

Align dimensions of the icon or illustration based on add item `size`:

- Use S2 illustrations in `large` and `medium` size components.
- Use S1 for `small` size component.
- Use 24×24 px or 18×18 px icons for `tiny` size component.

```jsx
<StorybookComponents.Stack width="50%" flexDirection="column">
  <Box height="212px">
    <AddItem
      size="large"
      icon={
        <StorybookComponents.Placeholder width="96px" height="96px">
          <StorybookComponents.Stack
            justifyContent="center"
            height="100%"
            alignItems="center"
          >
            <Text weight="bold" secondary>
              S2
            </Text>
          </StorybookComponents.Stack>
        </StorybookComponents.Placeholder>
      }
    >
      Large
    </AddItem>
  </Box>
  <Box height="162px">
    <AddItem
      size="medium"
      icon={
        <StorybookComponents.Placeholder width="96px" height="96px">
          <StorybookComponents.Stack
            justifyContent="center"
            height="100%"
            alignItems="center"
          >
            <Text weight="bold" secondary>
              S2
            </Text>
          </StorybookComponents.Stack>
        </StorybookComponents.Placeholder>
      }
    >
      Medium
    </AddItem>
  </Box>
  <Box height="120px">
    <AddItem
      size="small"
      icon={
        <StorybookComponents.Placeholder width="60px" height="60px">
          <StorybookComponents.Stack
            justifyContent="center"
            height="100%"
            alignItems="center"
          >
            <Text weight="bold" secondary>
              S1
            </Text>
          </StorybookComponents.Stack>
        </StorybookComponents.Placeholder>
      }
    >
      Small
    </AddItem>
  </Box>
  <Box>
    <AddItem size="tiny" icon={<Icons.Image />}>
      Tiny
    </AddItem>
  </Box>
  <Box>
    <AddItem size="tiny" icon={<Icons.ImageSmall />}>
      Tiny with small icon
    </AddItem>
  </Box>
</StorybookComponents.Stack>;
```

#### Disabled

Disable all component interactions with `disabled` prop. Use it to show that no new item can be added to the list at a moment.

```jsx
<AddItem disabled>Disabled</AddItem>;
```

#### Tooltip

Describe add item action with `tooltipContent`. Tooltip is shown when users hover on the item with a mouse.

Control tooltip design with `tooltipProps`.

```jsx
<AddItem
  tooltipContent="Description for the add item action"
  tooltipProps={{ placement: 'bottom' }}
>
  Hover to see tooltip
</AddItem>;
```

### Common use case examples

#### Inside a card

Use Add item to create a new item inside a card.

When the list consists mainly of textual content, use `plain` theme and adjust component's `alignment`.

```jsx
() => {
  const records = [
    {
      option: `Size`,
      vars: 'S, M, L',
    },
    {
      option: `Colors`,
      vars: 'Black, Neutral, White',
    },
    {
      option: 'Material',
      vars: 'Cotton, Eco leather',
    },
  ];

  const columns = [
    { title: 'Option', render: (row) => row.option },
    { title: 'Variations', render: (row) => row.vars },
  ];

  return (
    <Box>
      <Card hideOverflow>
        <Card.Header title="Product options"></Card.Header>
        <Table data={records} columns={columns} rowVerticalPadding="medium">
          <Table.Content />
          <AddItem theme="plain" alignItems="left">
            Add New Option
          </AddItem>
        </Table>
      </Card>
    </Box>
  );
};
```

#### Inside a page

Use Add item's `dashed` theme when component is placed directly inside of a `<Page/>` layout.

```jsx
<Page>
  <Page.Header title="Events" />
  <Page.Content>
    <Layout>
      <Cell span={12}>
        <Box height={160}>
          <Box align="center" verticalAlign="middle" width={180}>
            <Image
              height="180px"
              borderRadius="8px 0px 0px 8px"
              src="running_man.png"
            />
          </Box>
          <Box
            direction="vertical"
            borderRadius="0px 8px 8px 0px"
            verticalAlign="space-between"
            padding="18px 24px"
            backgroundColor="D80"
            flexGrow={1}
          >
            <Box verticalAlign="space-between" flexGrow={1}>
              <Box direction="vertical" gap="3px">
                <Heading size="small">Get running!</Heading>
                <Text size="small" secondary>
                  Scheduled for April 26, 2021
                </Text>
              </Box>
            </Box>
            <Box align="space-between">
              <Box gap="24px">
                <Box verticalAlign="middle" gap="0px">
                  <Icons.LockUnlockedSmall />
                  <Box marginLeft={1}>
                    <Text size="small">Public</Text>
                  </Box>
                </Box>
                <Box verticalAlign="middle">
                  <Box marginLeft={1}>
                    <Text size="small">Join for Free</Text>
                  </Box>
                </Box>
              </Box>
              <Box>
                <Box verticalAlign="middle">
                  <Box gap="SP2">
                    <IconButton priority="secondary" size="small">
                      <Icons.MoreSmall />
                    </IconButton>
                    <Button priority="secondary" size="small">
                      Edit
                    </Button>
                  </Box>
                </Box>
              </Box>
            </Box>
          </Box>
        </Box>
      </Cell>
      <Cell>
        <Box height={160}>
          <AddItem size="small">Add New Event</AddItem>
        </Box>
      </Cell>
    </Layout>
  </Page.Content>
</Page>;
```

#### Add images

Use Add item to upload images.

For this, select `image` theme and show the title inside a tooltip on mouse hover.

```jsx
<Card>
  <Card.Header title="Profile" />
  <Card.Divider />
  <Card.Content>
    <Layout>
      <Cell span={6}>
        <Box direction="vertical" gap="4">
          <FormField labelSize="small" label="Business name">
            <Input placeholder="" />
          </FormField>
          <FormField labelSize="small" label="Short description">
            <InputArea
              placeholder="Add more details about your business."
              rows={3}
              hasCounter
              resizable
            />
          </FormField>
        </Box>
      </Cell>
      <Cell span={6}>
        <FormField labelSize="small" label="Logo">
          <Dropzone onDrop={() => {}}>
            <Dropzone.Content>
              <FileUpload onChange={() => {}}>
                {({ openFileUploadDialog }) => (
                  <Box height="168px">
                    <AddItem
                      theme="image"
                      tooltipContent="Add Logo"
                      size="medium"
                      onClick={openFileUploadDialog}
                    />
                  </Box>
                )}
              </FileUpload>
            </Dropzone.Content>
          </Dropzone>
        </FormField>
      </Cell>
    </Layout>
  </Card.Content>
</Card>;
```

## Code

```jsx
import { AddItem } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `alignItems` | `"center" \| "right" \| "left"` | `'center'` | Controls the horizontal alignment of the content. |
| `ariaDescribedBy` | `string` | — | Defines the ID of the element that describes the add item element. |
| `ariaLabel` | `string` | — | Defines a string value that labels the add item element. |
| `ariaLabelledBy` | `string` | — | Defines the ID of the element that labels the add item element. |
| `borderRadius` | `string \| number \| string & {}` | — | Sets the `border-radius` CSS property of the button element. |
| `children` | `ReactNode \| (() => ReactNode)` | — | Accepts any renderable node or a render function to display as the content. Text styles aren't applied to the output of a render function. |
| `dataHook` | `string` | — | Applied as data-hook HTML attribute that can be used to create driver in testing. |
| `disabled` | `boolean` | — | Specifies whether the component is disabled. |
| `icon` | `ReactNode` | — | The illustration icon src or node. |
| `onClick` | `MouseEventHandler` | — | Defines a callback function which is called when the component is clicked. |
| `ref` | `null \| string \| (instance: AddItemActions \| null) => void \| RefObject<AddItemActions>` | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
| `removePadding` | `boolean` | `false` | Specifies whether to remove the padding around the content. |
| `showIcon` | `boolean` | `true` | Displays the plus icon. |
| `size` | `"small" \| "tiny" \| "medium" \| "large"` | `'tiny'` | Controls the size of the icon, text and spacing. |
| `skin` | `"image" \| "dashes" \| "plain" \| "filled"` | `'dashes'` | Controls the visual style of the component. |
| `subtitle` | `ReactNode` | — | Subtitle of the component. |
| `subtitlePlacement` | `"top" \| "bottom"` | `'bottom'` | Sets whether the subtitle shows below or above the title. With `top`, the subtitle shows between the icon and the title, except at `tiny` size, where the icon sits beside the title and the subtitle shows directly above the title. |
| `theme` | `"image" \| "dashes" \| "plain" \| "filled"` | — | Controls the visual style of the component. |
| `tooltipContent` | `ReactNode` | — | When provided, hovering displays a tooltip. |
| `tooltipProps` | `TooltipCommonProps` | — | Tooltip props. |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { AddItemUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { AddItemTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { AddItemTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { AddItemTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `getText` | Gets AddItem text |
| `textExists` | Checks whether AddItem text exist |
| `getTooltipContent` | Gets tooltip text |
| `getSubtitle` | Gets AddItem subtitle |
| `isFocused` | Checks whether AddItem is focused |
| `focus` | Sets focus on the element |
| `blur` | Removes focus on the element |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `click` | Clicks on the component root element. |
| `base` | Returns UniDriver for the base element. |

## Changelog

- **1.342.0** (2026-10-26) — feat: new `subtitlePlacement` prop. Set it to `top` to show the subtitle above the title; the default `bottom` keeps the current layout. ([#17596](invalid-url)) — has visual changes
- **1.340.0** (2026-10-21) — maintenance release, no component-specific changes
- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.332.0** (2026-10-05) — maintenance release, no component-specific changes
- **1.331.0** (2026-10-01) — fix: `ariaLabelledBy` and `ariaDescribedBy` now reach the button as `aria-labelledby` and `aria-describedby`, so screen readers announce the label and description you point them at. With a tooltip, the button is described by both your element and the tooltip. ([#17291](invalid-url))
- **1.330.3** (2026-09-29) — maintenance release, no component-specific changes
- **1.330.0** (2026-09-28) — maintenance release, no component-specific changes
- **1.329.0** (2026-09-24) — maintenance release, no component-specific changes
- **1.328.0** (2026-09-22) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.323.0** (2026-09-10) — maintenance release, no component-specific changes
- **1.320.0** (2026-09-03) — maintenance release, no component-specific changes
- **1.317.0** (2026-08-26) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.291.0** (2026-06-19) — maintenance release, no component-specific changes
- **1.278.0** (2026-05-08) — maintenance release, no component-specific changes
- **1.273.0** (2026-04-30) — maintenance release, no component-specific changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.247.2** (2026-01-21) — maintenance release, no component-specific changes
- **1.242.0** (2025-12-19) — maintenance release, no component-specific changes
- **1.217.0** (2025-09-08) — breaking: add token ([#15282](invalid-url))
- **1.216.0** (2025-09-01) — breaking: e3 tokenization ([#15257](invalid-url))
- **1.213.0** (2025-08-19) — fix: show tooltip on focus and add aria-describedby ([#15205](invalid-url))
- **1.212.0** (2025-08-11) — maintenance release, no component-specific changes
- **1.196.0** (2025-06-04) — maintenance release, no component-specific changes
- **1.165.0** (2025-02-27) — maintenance release, no component-specific changes
- **1.155.0** (2025-01-23) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.129.0** (2024-09-25) — fix: use default cursor for disabled state ([#14154](invalid-url))
- **1.124.0** (2024-09-06) — maintenance release, no component-specific changes
- **1.116.0** (2024-07-22) — maintenance release, no component-specific changes
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.104.1** (2024-05-14) — maintenance release, no component-specific changes
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.93.0** (2024-02-08) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes