> 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: Thumbnail Component

## Article: Thumbnail Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/form/thumbnail-component.md

## Article Content:

# Thumbnail

_Components/Form_

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

## Overview

```jsx
() => {
  const [selected, setSelected] = React.useState(0);
  return (
    <Box align="center" direction="horizontal" gap="24px">
      <Thumbnail
        title="Physical location"
        width={250}
        selected={selected === 0}
        onClick={() => setSelected(0)}
      />
      <Thumbnail
        title="Online"
        width={250}
        selected={selected === 1}
        onClick={() => setSelected(1)}
      />
    </Box>
  );
};
```

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`

```jsx
<StorybookComponents.Stack>
  <Thumbnail
    image={<Image />}
    title={
      <StorybookComponents.Placeholder>Title</StorybookComponents.Placeholder>
    }
    description={
      <StorybookComponents.Placeholder>
        Description
      </StorybookComponents.Placeholder>
    }
  />
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Thumbnail size="medium" title="Medium" description="Size" />
  <Thumbnail size="small" title="Small" description="Size" />
  <Thumbnail size="tiny" title="Tiny" description="Size" />
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack>
  <Thumbnail
    title="Skin"
    description="Default"
    image={<Image />}
    contentAlignment="top"
    width={165}
    height={200}
  />
  <Thumbnail
    title="Skin"
    skin="secondary"
    description="Secondary"
    image={<Image />}
    contentAlignment="top"
    width={165}
    height={200}
  />
</StorybookComponents.Stack>;
```

#### Dimensions

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Thumbnail title="Title" width="50%" height="120px" />
  <Thumbnail title="Title" width="25%" height="60px" />
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack>
  <Thumbnail
    title="Center"
    description="Alignment"
    image={<Image width="90px" />}
    height={240}
    contentAlignment="center"
    width={165}
  />
  <Thumbnail
    title="Top"
    description="Alignment"
    image={<Image width="90px" />}
    height={240}
    contentAlignment="top"
    width={165}
  />
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack>
  <Thumbnail
    title="Inside"
    description="Description"
    image={<Image />}
    contentAlignment="top"
    width={165}
    height={200}
  />
  <Thumbnail
    title="Outside"
    description="Alignment"
    image={<Image height="100%" />}
    contentAlignment="top"
    textPosition="outside"
    width={165}
    height={200}
  />
</StorybookComponents.Stack>;
```

#### Background image

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

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

```jsx
<Thumbnail
  backgroundImage="example.jpg"
  width={240}
  height={240}
  title="Title"
/>;
```

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

```jsx
<StorybookComponents.Stack gap="12px">
  <Thumbnail title="Default" width={140} />
  <Thumbnail title="Selected" selected width={140} />
  <Thumbnail title="Disabled" disabled width={140} />
  <Thumbnail
    title="Disabled with image"
    disabled
    image={<Image />}
    width={140}
  />
  <Thumbnail
    title="Disabled with image background"
    disabled
    backgroundImage="example.jpg"
    height={120}
    width={140}
  />
</StorybookComponents.Stack>;
```

#### 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/>`.

```jsx
<FormField status="error" statusMessage="This is an error message.">
  <StorybookComponents.Stack gap="12px">
    <Thumbnail title="Option 1" width={140} />
    <Thumbnail title="Option 2" width={140} />
    <Thumbnail title="Option 3" width={140} />
  </StorybookComponents.Stack>
</FormField>;
```

#### Custom content

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

```jsx
<Thumbnail title="Title" width="50%">
  <StorybookComponents.Stack padding="24px">
    <StorybookComponents.Placeholder>Content</StorybookComponents.Placeholder>
  </StorybookComponents.Stack>
</Thumbnail>;
```

### Common use case examples

#### List of options

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

```jsx
() => {
  const [selected, setSelected] = React.useState(0);

  const renderCell = ({ id, title, src }) => (
    <Cell span={2}>
      <Thumbnail
        size="small"
        title={<Text>{title}</Text>}
        selected={selected === id}
        onClick={() => setSelected(id)}
      >
        <Proportion>
          <Box height="100%" width="100%" align="center" verticalAlign="middle">
            <Image src={src} height="24px" width="24px" transparent />
          </Box>
        </Proportion>
      </Thumbnail>
    </Cell>
  );

  return (
    <Card>
      <Card.Header title="Add label to contact" />
      <Divider />
      <Card.Content>
        <Layout>
          <Cell span={12}>
            <Text>Decide how you want to respond to the trigger</Text>
          </Cell>
          {renderCell({
            id: 0,
            title: 'Send email to contacts',
            src: 'contacts.svg',
          })}
          {renderCell({
            id: 1,
            title: 'Send a chat message',
            src: 'chat_message.svg',
          })}
          {renderCell({
            id: 2,
            title: 'Get notified by email',
            src: 'email_notify.svg',
          })}
          {renderCell({
            id: 3,
            title: 'Create a task',
            src: 'task.svg',
          })}
        </Layout>
      </Card.Content>
    </Card>
  );
};
```

#### Gallery selection

Use a thumbnail with `backgroundImage` to construct gallery selections.

```jsx
() => {
  const [selected, setSelected] = React.useState(0);

  return (
    <Layout cols={1}>
      <FormField label="Cover Image">
        <Box gap="12px">
          <Thumbnail
            backgroundImage="TravelExample1.jpg"
            width={64}
            height={64}
            selected={selected === 0}
            onClick={() => setSelected(0)}
          />
          <Thumbnail
            backgroundImage="TravelExample2.jpg"
            width={64}
            height={64}
            selected={selected === 1}
            onClick={() => setSelected(1)}
          />
          <Thumbnail
            backgroundImage="TravelExample3.jpg"
            width={64}
            height={64}
            selected={selected === 2}
            onClick={() => setSelected(2)}
          />
          <Thumbnail
            backgroundImage="TravelExample4.jpg"
            width={64}
            height={64}
            selected={selected === 3}
            onClick={() => setSelected(3)}
          />
          <Thumbnail
            backgroundImage="TravelExample5.jpg"
            width={64}
            height={64}
            selected={selected === 4}
            onClick={() => setSelected(4)}
          />
        </Box>
      </FormField>
    </Layout>
  );
};
```

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

```jsx
() => {
  const [selected, setSelected] = React.useState(0);

  const renderThumbnail = ({ title, subtitle, id }) => (
    <Thumbnail selected={selected === id} onClick={() => setSelected(id)}>
      <Box padding="18px">
        <Box gap="12px" verticalAlign="middle">
          <Icons.Public />
          <Box direction="vertical">
            <Text size="medium" weight="bold">
              {title}
            </Text>
            <Box>
              <Text size="small" secondary>
                {subtitle}
              </Text>
            </Box>
          </Box>
        </Box>
      </Box>
    </Thumbnail>
  );

  return (
    <Card>
      <Card.Header title="Group info" />
      <Card.Divider />
      <Card.Content>
        <Layout cols={12}>
          <Cell span={8}>
            <Layout cols={1}>
              <FormField label="Name">
                <Input placeholder="Enter group name" />
              </FormField>
              <FormField
                label="Privacy"
                infoContent="Choose who can see and join this group"
              >
                <Layout cols={1} gap="12px">
                  {renderThumbnail({
                    title: 'Public',
                    subtitle: 'Anyone can view this group',
                    id: 0,
                  })}
                  {renderThumbnail({
                    title: 'Private',
                    subtitle: 'Only approved members can view this group',
                    id: 1,
                  })}
                  {renderThumbnail({
                    title: 'Hidden',
                    subtitle: 'Group is hidden and requires an invite to join',
                    id: 2,
                  })}
                </Layout>
              </FormField>
            </Layout>
          </Cell>
        </Layout>
      </Card.Content>
    </Card>
  );
};
```

#### Settings panel

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

```jsx
() => {
  const [selectedDirection, setSelectedDirection] = React.useState(0);
  const [selectedAlignment, setSelectedAlignment] = React.useState(1);

  return (
    <SidePanel onCloseButtonClick={() => {}} skin="floating" width="288px">
      <SidePanel.Header title="Text Input Layout" />
      <SidePanel.Content noPadding>
        <SidePanel.Field>
          <FieldSet
            legend="Direction"
            direction="horizontal"
            columns="auto auto"
          >
            <Thumbnail
              size="tiny"
              selected={selectedDirection === 0}
              onClick={() => setSelectedDirection(0)}
              hideSelectedIcon
              height={54}
              noPadding
              image={
                <Image
                  src="ThumbnailIllustration_LTR.svg"
                  transparent
                  fit="none"
                />
              }
              title="Left to right"
              textPosition="outside"
            />
            <Thumbnail
              size="tiny"
              selected={selectedDirection === 1}
              onClick={() => setSelectedDirection(1)}
              hideSelectedIcon
              height={54}
              noPadding
              image={
                <Image
                  src="ThumbnailIllustration_RTL.svg"
                  transparent
                  fit="none"
                />
              }
              title="Right to left"
              textPosition="outside"
            />
          </FieldSet>
        </SidePanel.Field>
        <SidePanel.Field>
          <FieldSet
            legend="Alignment"
            direction="horizontal"
            columns="38px 38px 38px"
          >
            <Thumbnail
              size="tiny"
              selected={selectedAlignment === 0}
              onClick={() => setSelectedAlignment(0)}
              hideSelectedIcon
              height={38}
              noPadding
              image={
                <Image
                  src="ThumbnailIllustration_AlignLeft.svg"
                  transparent
                  fit="none"
                />
              }
              textPosition="outside"
            />
            <Thumbnail
              size="tiny"
              selected={selectedAlignment === 1}
              onClick={() => setSelectedAlignment(1)}
              hideSelectedIcon
              height={38}
              noPadding
              image={
                <Image
                  src="ThumbnailIllustration_AlignCenter.svg"
                  transparent
                  fit="none"
                />
              }
              textPosition="outside"
            />
            <Thumbnail
              size="tiny"
              selected={selectedAlignment === 2}
              onClick={() => setSelectedAlignment(2)}
              hideSelectedIcon
              height={38}
              noPadding
              image={
                <Image
                  src="ThumbnailIllustration_AlignRight.svg"
                  transparent
                  fit="none"
                />
              }
              textPosition="outside"
            />
          </FieldSet>
        </SidePanel.Field>
      </SidePanel.Content>
    </SidePanel>
  );
};
```

## Code

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

### Props

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

## Testkit

Import the driver matching your test environment:

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

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

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

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

### Driver methods

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

## 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](invalid-url))
- **1.315.0** (2026-08-20) — fix: internal refactor of the component's styling by migrating to semantic classes. ([#16807](invalid-url))
- **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](invalid-url))
- **1.297.0** (2026-07-09) — fix: make tiny title font-weight deterministic ([#16517](invalid-url))
- **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](invalid-url))
- **1.254.0** (2026-02-03) — feat: add `secondary` skin ([#15878](invalid-url))
- **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](invalid-url))
- **1.219.0** (2025-09-12) — fix: allow pointer events on overlay ([#15302](invalid-url))
- **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](invalid-url))
- **1.174.0** (2025-03-28) — feat: add onMouseOver event handler ([#14680](invalid-url))
- **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](invalid-url))
- **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](invalid-url))
- **1.103.0** (2024-04-23) — breaking: title font weight fixed for size tiny ([#13586](invalid-url))
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes