AddItem

Components/Actions

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

Overview

Copy

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.
Copy

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.
Copy

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.

Copy

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.

Copy

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.

Copy

Title

Emphasize action with a title.

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

Copy

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.

Copy

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.
Copy

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.

Copy

Icon

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

Copy

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.
Copy

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.

Copy

Tooltip

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

Control tooltip design with tooltipProps.

Copy

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.

Copy

Inside a page

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

Copy

Add images

Use Add item to upload images.

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

Copy

Code

Copy

Props

NameTypeDefaultDescription
alignItems"center" | "right" | "left"'center'Controls the horizontal alignment of the content.
ariaDescribedBystring—Defines the ID of the element that describes the add item element.
ariaLabelstring—Defines a string value that labels the add item element.
ariaLabelledBystring—Defines the ID of the element that labels the add item element.
borderRadiusstring | number | string & {}—Sets the border-radius CSS property of the button element.
childrenReactNode | (() => 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.
dataHookstring—Applied as data-hook HTML attribute that can be used to create driver in testing.
disabledboolean—Specifies whether the component is disabled.
iconReactNode—The illustration icon src or node.
onClickMouseEventHandler—Defines a callback function which is called when the component is clicked.
refnull | 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).
removePaddingbooleanfalseSpecifies whether to remove the padding around the content.
showIconbooleantrueDisplays 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.
subtitleReactNode—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.
tooltipContentReactNode—When provided, hovering displays a tooltip.
tooltipPropsTooltipCommonProps—Tooltip props.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getTextGets AddItem text
textExistsChecks whether AddItem text exist
getTooltipContentGets tooltip text
getSubtitleGets AddItem subtitle
isFocusedChecks whether AddItem is focused
focusSets focus on the element
blurRemoves focus on the element
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns 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) — 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)
  • 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)
  • 1.216.0 (2025-09-01) — breaking: e3 tokenization (#15257)
  • 1.213.0 (2025-08-19) — fix: show tooltip on focus and add aria-describedby (#15205)
  • 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)
  • 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

Last updated: 26 October 2026

Did this help?