Components/Form
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/thumbnail
Thumbnails are used to display selectable items.
<SegmentedToggle/> or <SelectableAccordion/> instead.<ImageViewer/> instead.<Tabs/> instead.Thumbnails have 3 optional content areas:
imagetitledescriptionAdjust 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.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.
Set the dimensions of a thumbnail in pixels or percentages with the height and width properties.
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.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.Render an image as a thumbnail background with the backgroundImage prop.
This works well for gallery selections, such as product cover images.
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.
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/>.
Place any image, component or set of components inside the thumbnail content area.
Use a thumbnail to create a list of options with icons as visual cues.
Use a thumbnail with backgroundImage to construct gallery selections.
Render custom content inside of a thumbnail to give more details about each option.
For example, add graphics, images or links to learn more.
Use illustrations in thumbnails to demonstrate the result of the user's selection.
| Name | Type | Default | Description |
|---|---|---|---|
ariaLabel | string | — | Sets the aria-label attribute for accessibility. |
backgroundImage | ReactNode | — | Render image as a background of a thumbnail. As a result, title is rendered below the image thumbnail. |
border | boolean | true | Adds a border and corner radius. |
children | ReactNode | — | 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" | center | Controls vertical alignment of content. |
dataHook | string | — | Applies a data-hook HTML attribute that can be used in the tests. |
description | ReactNode | — | Sets thumbnail description. |
disabled | boolean | false | Specifies whether thumbnail interactions are disabled. |
ellipsis | boolean | false | Enables ellipsis text truncation. |
focusableOnBlur | FocusEventHandler | — | |
focusableOnFocus | FocusEventHandler | — | |
height | string | number | — | Controls the height of a thumbnail. |
hideSelectedIcon | boolean | — | Hides a checkmark icon that indicates selected thumbnail. The selected option is highlighted with a border only. |
image | ReactNode | — | 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. |
maxLines | number | — | Controls maximum lines that is allowed before ellipsis text truncation is applied. |
noPadding | boolean | false | Turns 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. |
ref | string & 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). |
selected | boolean | false | Specifies whether a thumbnail is selected. |
size | "small" | "tiny" | "medium" | medium | Controls the size of a thumbnail. |
skin | "primary" | "secondary" | primary | Controls the skin (visual style) of a thumbnail. |
textPosition | "inside" | "outside" | inside | Controls text position whether it is outside or inside of a thumbnail. |
title | ReactNode | — | Sets the title of a thumbnail. |
tooltipProps | TooltipCommonProps | — | Allows to pass tooltip common props. |
width | string | number | — | Controls the width of a thumbnail. |
Import the driver matching your test environment:
| Method | Description |
|---|---|
getTitle | Gets thumbnail title |
getDescription | Gets thumbnail description |
getSelectedIcon | Gets selected icon driver |
getBackgroundImage | Gets background image driver |
isSelected | Checks whether Thumbnail is selected |
isDisabled | Checks whether Thumbnail is disabled |
getImage | Gets thumbnail image driver |
getWidth | Gets thumbnail width, if it's set through width prop |
getHeight | Gets thumbnail height, if it's set through height prop |
getAriaLabel | Gets aria-label attribute |
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. |
textPosition="outside" thumbnails and is held for as long as the thumbnail stays selected. (#16835)secondary skin (#15878)Last updated: 22 October 2026