Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(thumbnail): add showRemoveOn prop (#4300)

Kenton Quatman07362a91d8eb
diff --git a/.changeset/thumbnail-show-remove-on.md b/.changeset/thumbnail-show-remove-on.md
new file mode 100644
index 0000000000..289520db03
--- /dev/null
+++ b/.changeset/thumbnail-show-remove-on.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Thumbnail: add `showRemoveOn` prop — `'hover'` (default) reveals the remove button on hover or keyboard focus and keeps it visible on touch; `'always'` shows it at rest.
+
+@kentonquatman
diff --git a/apps/storybook/stories/Thumbnail.stories.tsx b/apps/storybook/stories/Thumbnail.stories.tsx
index caac34ef76..0ba3db37ad 100644
--- a/apps/storybook/stories/Thumbnail.stories.tsx
+++ b/apps/storybook/stories/Thumbnail.stories.tsx
@@ -25,6 +25,11 @@ const meta: Meta<typeof Thumbnail> = {
control: 'boolean',
description: 'Whether the thumbnail is disabled',
},
+ showRemoveOn: {
+ control: 'inline-radio',
+ options: ['always', 'hover'],
+ description: 'When the remove button is visible',
+ },
},
};
@@ -67,12 +72,53 @@ export const WithRemove: Story = {
src={LIGHT_IMAGE}
alt="Removable thumbnail"
label="photo.png"
+ showRemoveOn="always"
onRemove={() => setVisible(false)}
/>
);
},
};
+export const RemoveOnHover: Story = {
+ name: 'Remove on hover',
+ render: () => {
+ const initial = [
+ {id: 1, src: LIGHT_IMAGE, label: 'light.jpg', alt: 'Light image'},
+ {id: 2, src: WARM_IMAGE, label: 'warm.jpg', alt: 'Warm tones'},
+ {id: 3, src: MIXED_IMAGE, label: 'mixed.jpg', alt: 'Mixed tones'},
+ ];
+ const [items, setItems] = useState(initial);
+ return (
+ <div>
+ <p style={{fontSize: 12, color: '#888', marginBottom: 8}}>
+ Remove button is hidden until you hover the thumbnail (or focus it
+ with the keyboard).
+ </p>
+ <div style={{display: 'flex', gap: 8, alignItems: 'flex-start'}}>
+ {items.map(item => (
+ <Thumbnail
+ key={item.id}
+ src={item.src}
+ alt={item.alt}
+ label={item.label}
+ showRemoveOn="hover"
+ onRemove={() =>
+ setItems(prev => prev.filter(i => i.id !== item.id))
+ }
+ />
+ ))}
+ {items.length === 0 && (
+ <p style={{color: '#888', fontSize: 12}}>
+ All removed.{' '}
+ <button onClick={() => setItems(initial)}>Reset</button>
+ </p>
+ )}
+ </div>
+ </div>
+ );
+ },
+};
+
export const WithCaption: Story = {
render: () => {
const [visible, setVisible] = useState(true);
@@ -88,6 +134,7 @@ export const WithCaption: Story = {
src={WARM_IMAGE}
alt="Photo with metadata"
label="screenshot.png"
+ showRemoveOn="always"
onRemove={() => setVisible(false)}
/>
);
@@ -132,7 +179,13 @@ export const Placeholder: Story = {
</p>
);
}
- return <Thumbnail label="report.pdf" onRemove={() => setVisible(false)} />;
+ return (
+ <Thumbnail
+ label="report.pdf"
+ showRemoveOn="always"
+ onRemove={() => setVisible(false)}
+ />
+ );
},
};
@@ -169,6 +222,7 @@ export const MediaModeTest: Story = {
src={item.src}
alt={item.alt}
label={item.label}
+ showRemoveOn="always"
onRemove={() =>
setItems(prev => prev.filter(i => i.label !== item.label))
}
@@ -202,6 +256,7 @@ export const Gallery: Story = {
src={item.src}
alt={item.label}
label={item.label}
+ showRemoveOn="always"
onRemove={() =>
setItems(prev => prev.filter(i => i.id !== item.id))
}
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailDisabled.tsx b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailDisabled.tsx
index 6a3173a3be..4e0e76521c 100644
--- a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailDisabled.tsx
+++ b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailDisabled.tsx
@@ -23,9 +23,14 @@ export default function ThumbnailDisabled() {
src={GOLDEN_SUNSET}
alt="Golden sunset over mountains"
label="golden-sunset.jpg"
+ showRemoveOn="always"
+ onRemove={() => {}}
+ />
+ <Thumbnail
+ label="document.pdf"
+ showRemoveOn="always"
onRemove={() => {}}
/>
- <Thumbnail label="document.pdf" onRemove={() => {}} />
</Stack>
</Stack>
<Stack direction="vertical" gap={1}>
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailGallery.tsx b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailGallery.tsx
index abb32e114a..2228feb7c7 100644
--- a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailGallery.tsx
+++ b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailGallery.tsx
@@ -66,6 +66,7 @@ export default function ThumbnailGallery() {
src={item.src}
alt={item.alt}
label={item.label}
+ showRemoveOn="always"
onClick={() => setSelected(item.label)}
onRemove={() =>
setItems(prev => prev.filter(i => i.id !== item.id))
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailRemovable.tsx b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailRemovable.tsx
index 02d75af854..62e5047dee 100644
--- a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailRemovable.tsx
+++ b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailRemovable.tsx
@@ -65,6 +65,7 @@ export default function ThumbnailRemovable() {
src={item.src}
alt={item.alt}
label={item.label}
+ showRemoveOn="always"
onRemove={() =>
setItems(prev => prev.filter(i => i.id !== item.id))
}
diff --git a/packages/core/src/Thumbnail/Thumbnail.doc.mjs b/packages/core/src/Thumbnail/Thumbnail.doc.mjs
index f2778c1259..28db5fd15a 100644
--- a/packages/core/src/Thumbnail/Thumbnail.doc.mjs
+++ b/packages/core/src/Thumbnail/Thumbnail.doc.mjs
@@ -45,6 +45,13 @@ export const docs = {
description: 'Whether the thumbnail is disabled.',
default: 'false',
},
+ {
+ name: 'showRemoveOn',
+ type: "'always' | 'hover'",
+ description:
+ 'When the remove button is visible. `hover` (the default) reveals it on hover and on keyboard focus, and keeps it visible on any touch-capable device; `always` shows it at rest. Only applies when `onRemove` is set.',
+ default: "'hover'",
+ },
{
name: 'xstyle',
type: 'StyleXStyles',
@@ -101,6 +108,7 @@ export const docsZh = {
onClick: '\u70B9\u51FB\u5904\u7406\u5668\u3002\u6DFB\u52A0\u6309\u94AE\u8BED\u4E49\u548C\u60AC\u505C\u8986\u76D6\u5C42\u3002',
isLoading: '\u663E\u793A\u9AA8\u67B6\u5C4F\uFF08\u65E0 src\uFF09\u6216\u4E0A\u4F20\u8986\u76D6\u5C42\uFF08\u6709 src\uFF09\u3002',
isDisabled: '\u662F\u5426\u7981\u7528\u7F29\u7565\u56FE\u3002',
+ showRemoveOn: '\u4F55\u65F6\u663E\u793A\u79FB\u9664\u6309\u94AE\uFF1Ahover\uFF08\u9ED8\u8BA4\uFF0C\u60AC\u505C\u65F6\u4EE5\u53CA\u952E\u76D8\u805A\u7126\u65F6\u663E\u793A\uFF0C\u89E6\u6478\u8BBE\u5907\u4E0A\u4FDD\u6301\u53EF\u89C1\uFF09| always\uFF08\u59CB\u7EC8\u663E\u793A\uFF09\u3002\u4EC5\u5728\u8BBE\u7F6E onRemove \u65F6\u751F\u6548\u3002',
xstyle: '\u7528\u4E8E\u5E03\u5C40\u81EA\u5B9A\u4E49\u7684 StyleX \u6837\u5F0F\u3002\u5FC5\u987B\u662F stylex.create() \u7684\u503C\uFF0C\u800C\u975E\u5185\u8054\u6837\u5F0F\u5BF9\u8C61\u3002',
className: '\u6839\u5143\u7D20\u7684 CSS \u7C7B\u540D\u3002\u5EFA\u8BAE\u4F7F\u7528 xstyle\u3002',
style: '\u6839\u5143\u7D20\u7684\u5185\u8054\u6837\u5F0F\u3002\u5EFA\u8BAE\u4F7F\u7528 xstyle\u3002',
@@ -141,6 +149,7 @@ export const docsDense = {
onClick: '(e) => void. Adds button semantics + hover overlay.',
isLoading: 'Skeleton (no src) or upload overlay (with src). Default: false.',
isDisabled: 'Disabled state. Default: false.',
+ showRemoveOn: "When remove button shows: hover (default — reveal on hover/focus, stays visible on touch) | always. Only when onRemove set.",
xstyle: 'stylex.create() for layout.',
className: 'CSS class. Prefer xstyle.',
style: 'Inline styles. Prefer xstyle.',
diff --git a/packages/core/src/Thumbnail/Thumbnail.test.tsx b/packages/core/src/Thumbnail/Thumbnail.test.tsx
index dece8b3a2a..0319e2a937 100644
--- a/packages/core/src/Thumbnail/Thumbnail.test.tsx
+++ b/packages/core/src/Thumbnail/Thumbnail.test.tsx
@@ -163,4 +163,60 @@ describe('Thumbnail', () => {
render(<Thumbnail ref={ref} data-testid="thumb" />);
expect(ref).toHaveBeenCalled();
});
+
+ describe('showRemoveOn', () => {
+ // The reveal style lives on the slot <div> that wraps the remove button
+ // (ancestor-marker styles can't ride on a child component's xstyle prop),
+ // so assert on the button's parent element.
+ const removeSlotClass = (
+ showRemoveOn?: 'always' | 'hover',
+ ): {className: string; unmount: () => void} => {
+ const view = render(
+ <Thumbnail
+ label="file.png"
+ onRemove={vi.fn()}
+ showRemoveOn={showRemoveOn}
+ />,
+ );
+ const slot = screen.getByRole('button', {
+ name: 'Remove file.png',
+ }).parentElement!;
+ return {className: slot.className, unmount: view.unmount};
+ };
+
+ it('renders the remove button in the DOM even when showRemoveOn="hover"', () => {
+ // Hover reveal is CSS-only (opacity) — the button must stay mounted so
+ // it remains reachable by keyboard and assistive tech.
+ render(
+ <Thumbnail label="file.png" onRemove={vi.fn()} showRemoveOn="hover" />,
+ );
+ expect(
+ screen.getByRole('button', {name: 'Remove file.png'}),
+ ).toBeInTheDocument();
+ });
+
+ it('applies a distinct slot class when showRemoveOn="hover" vs "always"', () => {
+ const always = removeSlotClass('always');
+ always.unmount();
+ const hover = removeSlotClass('hover');
+ expect(hover.className).not.toBe(always.className);
+ });
+
+ it('defaults to "hover" (same slot class as an explicit hover)', () => {
+ const def = removeSlotClass(undefined);
+ def.unmount();
+ const hover = removeSlotClass('hover');
+ expect(def.className).toBe(hover.className);
+ });
+
+ it('still fires onRemove when revealed on hover', async () => {
+ const user = userEvent.setup();
+ const onRemove = vi.fn();
+ render(
+ <Thumbnail label="file.png" onRemove={onRemove} showRemoveOn="hover" />,
+ );
+ await user.click(screen.getByRole('button', {name: 'Remove file.png'}));
+ expect(onRemove).toHaveBeenCalledOnce();
+ });
+ });
});
diff --git a/packages/core/src/Thumbnail/Thumbnail.tsx b/packages/core/src/Thumbnail/Thumbnail.tsx
index 3faef893b1..8e35dbab55 100644
--- a/packages/core/src/Thumbnail/Thumbnail.tsx
+++ b/packages/core/src/Thumbnail/Thumbnail.tsx
@@ -43,6 +43,7 @@ import type {BaseProps} from '../BaseProps';
import {mergeProps} from '../utils';
import {themeProps} from '../utils/themeProps';
import {useTranslator} from '../i18n';
+import {thumbnailScope} from './thumbnail.markers.stylex';
export interface ThumbnailProps extends BaseProps<HTMLDivElement> {
/** Ref forwarded to the root element */
@@ -96,6 +97,17 @@ export interface ThumbnailProps extends BaseProps<HTMLDivElement> {
* @default false
*/
isDisabled?: boolean;
+ /**
+ * When the remove button is visible.
+ * - `'hover'` — the button is revealed on hover, and on keyboard focus so
+ * it stays reachable. On any touch-capable device it stays visible.
+ * This is the default.
+ * - `'always'` — the button is always shown.
+ *
+ * Only has an effect when `onRemove` is set.
+ * @default 'hover'
+ */
+ showRemoveOn?: 'always' | 'hover';
/**
* Test ID for testing frameworks.
*/
@@ -192,11 +204,14 @@ const styles = stylex.create({
overflow: 'hidden',
},
- removeButtonOverrides: {
+ removeSlot: {
position: 'absolute',
top: spacingVars['--spacing-1'],
right: spacingVars['--spacing-1'],
zIndex: 1,
+ lineHeight: 0,
+ },
+ removeButtonOverrides: {
'--_button-radius': `calc(${radiusVars['--radius-element']} - ${spacingVars['--spacing-1']})`,
height: 20,
minWidth: 20,
@@ -221,6 +236,28 @@ const styles = stylex.create({
zIndex: 1,
lineHeight: 0,
},
+ // showRemoveOn="hover": the remove button is hidden at rest and revealed
+ // when the thumbnail is hovered or when focus enters it (keyboard). Only
+ // opacity is animated — the button stays mounted and focusable so tabbing
+ // to it triggers the :focus-within reveal. Any touch-capable device (incl.
+ // hybrid laptops that also report hover) keeps the button visible so the
+ // remove path is never gated behind an unavailable hover.
+ removeOnHover: {
+ opacity: {
+ default: 0,
+ [stylex.when.ancestor(':hover', thumbnailScope)]: {
+ '@media (hover: hover)': 1,
+ },
+ [stylex.when.ancestor(':focus-within', thumbnailScope)]: 1,
+ '@media (any-pointer: coarse)': 1,
+ },
+ transitionProperty: 'opacity',
+ transitionDuration: {
+ default: durationVars['--duration-fast'],
+ '@media (prefers-reduced-motion: reduce)': '0s',
+ },
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
});
// =============================================================================
@@ -249,7 +286,8 @@ function ImagePlaceholder() {
*
* Shows a skeleton shimmer while the image loads, the image on success, or
* a placeholder icon on failure / when no src is provided. An overlaid
- * remove button appears when `onRemove` is set.
+ * remove button appears when `onRemove` is set — revealed on hover or
+ * keyboard focus by default (`showRemoveOn`), or always shown.
*
* The remove button uses a fixed `--color-overlay` scrim with an
* `--color-on-dark` icon so it stays legible on any image without sampling
@@ -259,6 +297,7 @@ function ImagePlaceholder() {
* ```
* <Thumbnail src="/photo.jpg" alt="Vacation photo" onRemove={() => {}} />
* <Thumbnail src="/preview.png" alt="Preview" onClick={() => {}} label="preview.png" />
+ * <Thumbnail src="/logo.png" alt="Logo" onRemove={() => {}} showRemoveOn="always" />
* ```
*/
export function Thumbnail({
@@ -269,6 +308,7 @@ export function Thumbnail({
onClick,
isLoading = false,
isDisabled = false,
+ showRemoveOn = 'hover',
xstyle,
className,
style,
@@ -284,6 +324,8 @@ export function Thumbnail({
const showUploadOverlay = isLoading && hasSrc;
const showPlaceholder = !isLoading && !hasSrc;
const isInteractive = onClick != null && !isDisabled && !isLoading;
+ const hasRemove = onRemove != null && !isDisabled;
+ const isHoverReveal = hasRemove && showRemoveOn === 'hover';
const accessibleName =
label && alt
? `${label} — ${alt}`
@@ -333,8 +375,12 @@ export function Thumbnail({
</>
);
- const removeButtonEl =
- onRemove != null && !isDisabled ? (
+ const removeButtonEl = hasRemove ? (
+ <div
+ {...stylex.props(
+ styles.removeSlot,
+ isHoverReveal && styles.removeOnHover,
+ )}>
<Button
icon={<Icon icon="close" size="xsm" />}
label={t('@astryx.thumbnail.remove', {accessibleName})}
@@ -347,7 +393,8 @@ export function Thumbnail({
}}
xstyle={styles.removeButtonOverrides}
/>
- ) : null;
+ </div>
+ ) : null;
const thumbnail = (
<div
@@ -365,6 +412,7 @@ export function Thumbnail({
<div
{...stylex.props(
styles.imageContainer,
+ isHoverReveal && thumbnailScope,
isInteractive && styles.interactive,
isInteractive && styles.overlay,
isInteractive && styles.hoverOnPointer,
diff --git a/packages/core/src/Thumbnail/thumbnail.markers.stylex.ts b/packages/core/src/Thumbnail/thumbnail.markers.stylex.ts
new file mode 100644
index 0000000000..1232101834
--- /dev/null
+++ b/packages/core/src/Thumbnail/thumbnail.markers.stylex.ts
@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * Scoped marker for Thumbnail ancestor selectors. Applied to the image
+ * container so the remove button's hover/focus reveal (`showRemoveOn="hover"`)
+ * responds only to this thumbnail — not to hover/focus state from an outer
+ * container the thumbnail happens to sit inside.
+ */
+export const thumbnailScope: ReturnType<typeof stylex.defineMarker> =
+ stylex.defineMarker();