Thumbnail

Components/Form

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

Overview

Copy

Thumbnails are used to display selectable items.

Do

  • Use it for selecting one or more items from a list of options.
  • Use it when selectable items need graphics or images.
  • Use it to build gallery selections.

Don't

  • Don't use it to switch between alternative options or views. Use <SegmentedToggle/> or <SelectableAccordion/> instead.
  • Don't use it to display images. Use <ImageViewer/> instead.
  • Don't use it to distribute content within a page. Use <Tabs/> instead.

Feature examples

Structure

Thumbnails have 3 optional content areas:

  • image
  • title
  • description
Copy

Size

Adjust the component size using size prop. It supports 3 sizes:

  • medium (default) is the standard used in common cases.
  • small is used for smaller elements and more compact designs.
  • tiny is best for dense layouts.
Copy

Skin

Change the thumbnail appearance using the skin prop. Two skin options are currently available. Use the secondary skin in panels that include thumbnails, such as environments like the Wix Harmony Editor.

Copy

Dimensions

Set the dimensions of a thumbnail in pixels or percentages with the height and width properties.

Copy

Content alignment

Control the vertical alignment of thumbnail content with the contentAlignment prop. It supports 2 options:

  • center (default) is the standard used for common cases.
  • top is used when the thumbnail list contains items with different content lengths.
Copy

Text position

Control the thumbnail text position with the textPosition prop.

  • inside (default) is used for text-only thumbnails or thumbnails that require more emphasis.
  • outside is used for side panel thumbnails or for a large group of illustrated thumbnails.
Copy

Background image

Render an image as a thumbnail background with the backgroundImage prop.

This works well for gallery selections, such as product cover images.

Copy

States

Control the state of a component with:

  • selected to mark active selection.
  • disabled to mark an item that cannot be selected or deselected.

Remove the selected item checkmark icon with the hideSelectedIcon prop.

Copy

Status message

Add text that explains the status or what action the user should take with the statusMessage prop.

Show the status message inline, directly below the thumbnails, by wrapping it in a <FormField/> and adding statusMessage.

View more inline status message examples in <FormField/>.

Copy

Custom content

Place any image, component or set of components inside the thumbnail content area.

Copy

Common use case examples

List of options

Use a thumbnail to create a list of options with icons as visual cues.

Copy

Use a thumbnail with backgroundImage to construct gallery selections.

Copy

Custom content with details

Render custom content inside of a thumbnail to give more details about each option.

For example, add graphics, images or links to learn more.

Copy

Settings panel

Use illustrations in thumbnails to demonstrate the result of the user's selection.

Copy

Code

Copy

Props

NameTypeDefaultDescription
ariaLabelstring—Sets the aria-label attribute for accessibility.
backgroundImageReactNode—Render image as a background of a thumbnail. As a result, title is rendered below the image thumbnail.
borderbooleantrueAdds a border and corner radius.
childrenReactNode—Renders specified children items inside of the thumbnail. Accepts any kind of content. When passed, the title is rendered below the thumbnail.
contentAlignment"center" | "top"centerControls vertical alignment of content.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
descriptionReactNode—Sets thumbnail description.
disabledbooleanfalseSpecifies whether thumbnail interactions are disabled.
ellipsisbooleanfalseEnables ellipsis text truncation.
focusableOnBlurFocusEventHandler—
focusableOnFocusFocusEventHandler—
heightstring | number—Controls the height of a thumbnail.
hideSelectedIconboolean—Hides a checkmark icon that indicates selected thumbnail. The selected option is highlighted with a border only.
imageReactNode—Specifies an image to be displayed inside of a thumbnail. If given as a string, it is used within <img/>. Otherwise can be given as React.Node.
maxLinesnumber—Controls maximum lines that is allowed before ellipsis text truncation is applied.
noPaddingbooleanfalseTurns off padding for thumbnail with textPosition='inside'
onBlur(event: FocusEvent, triggers: Triggers) => void—
onClick(event: MouseEvent<HTMLElement, MouseEvent> | KeyboardEvent<HTMLElement>) => void—Defines a callback function which is called every time a thumbnail is clicked.
onFocus(event: FocusEvent, triggers: Triggers) => void—
onMouseOver(event: MouseEvent<HTMLElement, MouseEvent>) => void—Defines a callback function which is called every time mouse is over a thumbnail.
refstring & RefObject<HTMLElement> | ((instance: { focus: () => void; } | null) => void) & RefObject<HTMLElement> | RefObject<{ focus: () => void; }> & RefObject<HTMLElement>—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).
selectedbooleanfalseSpecifies whether a thumbnail is selected.
size"small" | "tiny" | "medium"mediumControls the size of a thumbnail.
skin"primary" | "secondary"primaryControls the skin (visual style) of a thumbnail.
textPosition"inside" | "outside"insideControls text position whether it is outside or inside of a thumbnail.
titleReactNode—Sets the title of a thumbnail.
tooltipPropsTooltipCommonProps—Allows to pass tooltip common props.
widthstring | number—Controls the width of a thumbnail.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getTitleGets thumbnail title
getDescriptionGets thumbnail description
getSelectedIconGets selected icon driver
getBackgroundImageGets background image driver
isSelectedChecks whether Thumbnail is selected
isDisabledChecks whether Thumbnail is disabled
getImageGets thumbnail image driver
getWidthGets thumbnail width, if it's set through width prop
getHeightGets thumbnail height, if it's set through height prop
getAriaLabelGets aria-label attribute
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.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.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.324.0 (2026-09-14) — 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.316.0 (2026-08-25) — feat: selecting an image thumbnail in Harmony (odeditor) now animates — the image zooms in, the border transitions into the selected state, and the checkmark badge rises into place once the zoom settles. The zoom applies to textPosition="outside" thumbnails and is held for as long as the thumbnail stays selected. (#16835)
  • 1.315.0 (2026-08-20) — fix: internal refactor of the component's styling by migrating to semantic classes. (#16807)
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.303.0 (2026-07-23) — feat: allow selection of default props through the WixDesignSystemDefaultPropsProvider (#16618)
  • 1.297.0 (2026-07-09) — fix: make tiny title font-weight deterministic (#16517)
  • 1.295.0 (2026-07-03) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.273.0 (2026-04-30) — maintenance release, no component-specific changes
  • 1.272.0 (2026-04-27) — 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.257.0 (2026-02-19) — fix: secondary skin background (#15924)
  • 1.254.0 (2026-02-03) — feat: add secondary skin (#15878)
  • 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.224.0 (2025-10-30) — maintenance release, no component-specific changes
  • 1.223.0 (2025-10-27) — feat: aria-label (#15436)
  • 1.219.0 (2025-09-12) — fix: allow pointer events on overlay (#15302)
  • 1.216.0 (2025-09-01) — maintenance release, no component-specific changes
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.207.0 (2025-07-24) — feat: focus method (#15115)
  • 1.174.0 (2025-03-28) — feat: add onMouseOver event handler (#14680)
  • 1.172.1 (2025-03-21) — maintenance release, no component-specific changes
  • 1.169.0 (2025-03-10) — maintenance release, no component-specific changes
  • 1.161.0 (2025-02-12) — feat: expose tooltip props (#14523)
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.128.0 (2024-09-19) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.103.1 (2024-04-24) — maintenance release, no component-specific changes
  • 1.103.0 (2024-04-23) — fix: don't throw error on Enter and no onClick (#13647)
  • 1.103.0 (2024-04-23) — breaking: title font weight fixed for size tiny (#13586)
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?