Skip to content

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

TypeScript

feat(selector): add ghost variant (#4684)

Cindy Zhangebed74fa3d13
diff --git a/.changeset/ghost-selector-variants.md b/.changeset/ghost-selector-variants.md
new file mode 100644
index 0000000000..3340a7fa5d
--- /dev/null
+++ b/.changeset/ghost-selector-variants.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Add a ghost trigger variant for Selector and MultiSelector for toolbar-style controls, with ghost status messages detached by default.
+
+@cixzhang
diff --git a/apps/storybook/stories/MultiSelector.stories.tsx b/apps/storybook/stories/MultiSelector.stories.tsx
index bd560d7d59..ebf092907d 100644
--- a/apps/storybook/stories/MultiSelector.stories.tsx
+++ b/apps/storybook/stories/MultiSelector.stories.tsx
@@ -2,6 +2,7 @@
import type {Meta, StoryObj} from '@storybook/react';
import {useState} from 'react';
+import {Button} from '@astryxdesign/core/Button';
import {MultiSelector} from '@astryxdesign/core/MultiSelector';
import {Theme, defineTheme} from '@astryxdesign/core/theme';
@@ -25,6 +26,7 @@ const meta: Meta<typeof MultiSelector> = {
description: {control: 'text'},
placeholder: {control: 'text'},
size: {control: 'radio', options: ['sm', 'md', 'lg']},
+ variant: {control: 'radio', options: ['input', 'ghost']},
triggerDisplay: {
control: 'radio',
options: ['count', 'labels', 'badges'],
@@ -269,6 +271,51 @@ export const DisabledWithMessage: Story = {
decorators: [Story => <Story />],
};
+// Ghost variant for toolbar composition
+export const GhostVariant: Story = {
+ render: () => {
+ const [columns, setColumns] = useState<string[]>(['Name', 'Email']);
+ const [filters, setFilters] = useState<string[]>(['Active']);
+ return (
+ <div
+ style={{
+ display: 'flex',
+ alignItems: 'center',
+ gap: 8,
+ width: 'max-content',
+ }}>
+ <Button label="Refresh" variant="ghost" />
+ <MultiSelector
+ label="Columns"
+ isLabelHidden
+ variant="ghost"
+ size="md"
+ options={['Name', 'Email', 'Role', 'Status', 'Created']}
+ value={columns}
+ onChange={setColumns}
+ triggerDisplay="labels"
+ placeholder="Columns"
+ />
+ <MultiSelector
+ label="Status"
+ isLabelHidden
+ variant="ghost"
+ size="md"
+ options={['Active', 'Inactive', 'Pending', 'Archived']}
+ value={filters}
+ onChange={setFilters}
+ triggerDisplay="labels"
+ placeholder="Status"
+ status={{type: 'warning', message: 'Some filters hide archived rows'}}
+ statusVariant="tooltip"
+ />
+ <Button label="Export" variant="ghost" />
+ </div>
+ );
+ },
+ decorators: [Story => <Story />],
+};
+
// Status variants
export const Status: Story = {
render: () => {
diff --git a/apps/storybook/stories/Selector.stories.tsx b/apps/storybook/stories/Selector.stories.tsx
index a1f2882e6c..53a6e8a8e8 100644
--- a/apps/storybook/stories/Selector.stories.tsx
+++ b/apps/storybook/stories/Selector.stories.tsx
@@ -2,6 +2,7 @@
import type {Meta, StoryObj} from '@storybook/react';
import {useState} from 'react';
+import {Button} from '@astryxdesign/core/Button';
import {Selector, SelectorOption} from '@astryxdesign/core/Selector';
import {Theme, defineTheme} from '@astryxdesign/core/theme';
import {UserIcon, CogIcon, BellIcon} from '@heroicons/react/24/outline';
@@ -51,6 +52,11 @@ const meta: Meta<typeof Selector> = {
options: ['sm', 'md', 'lg'],
description: 'Size variant of the selector',
},
+ variant: {
+ control: 'radio',
+ options: ['input', 'ghost'],
+ description: 'Visual trigger style',
+ },
placement: {
control: 'select',
options: ['above', 'below', 'start', 'end'],
@@ -435,6 +441,55 @@ export const SizeVariants: Story = {
decorators: [Story => <Story />],
};
+// Ghost variant for toolbar composition
+export const GhostVariant: Story = {
+ render: () => {
+ const [view, setView] = useState<string | undefined>('week');
+ const [density, setDensity] = useState<string | undefined>('comfortable');
+ return (
+ <div
+ style={{
+ display: 'flex',
+ alignItems: 'center',
+ gap: 8,
+ width: 'max-content',
+ }}>
+ <Button label="Today" variant="ghost" />
+ <Selector
+ label="View"
+ isLabelHidden
+ variant="ghost"
+ size="md"
+ options={[
+ {value: 'day', label: 'Day'},
+ {value: 'week', label: 'Week'},
+ {value: 'month', label: 'Month'},
+ ]}
+ value={view}
+ onChange={setView}
+ />
+ <Selector
+ label="Density"
+ isLabelHidden
+ variant="ghost"
+ size="md"
+ options={[
+ {value: 'compact', label: 'Compact'},
+ {value: 'comfortable', label: 'Comfortable'},
+ {value: 'spacious', label: 'Spacious'},
+ ]}
+ value={density}
+ onChange={setDensity}
+ status={{type: 'warning', message: 'This setting affects all users'}}
+ statusVariant="tooltip"
+ />
+ <Button label="Export" variant="ghost" />
+ </div>
+ );
+ },
+ decorators: [Story => <Story />],
+};
+
// With status
export const WithStatus: Story = {
render: () => {
diff --git a/packages/cli/assets/templates/blocks/components/MultiSelector/MultiSelectorGhostToolbar.doc.mjs b/packages/cli/assets/templates/blocks/components/MultiSelector/MultiSelectorGhostToolbar.doc.mjs
new file mode 100644
index 0000000000..a48802fc63
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/MultiSelector/MultiSelectorGhostToolbar.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'MultiSelector',
+ name: 'MultiSelector — Ghost Toolbar',
+ displayName: 'MultiSelector — Ghost Toolbar',
+ description:
+ 'Borderless MultiSelector variant composed with ghost buttons in a toolbar.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['MultiSelector', 'Button', 'HStack'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/MultiSelector/MultiSelectorGhostToolbar.tsx b/packages/cli/assets/templates/blocks/components/MultiSelector/MultiSelectorGhostToolbar.tsx
new file mode 100644
index 0000000000..2a050d39b2
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/MultiSelector/MultiSelectorGhostToolbar.tsx
@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Button} from '@astryxdesign/core/Button';
+import {HStack} from '@astryxdesign/core/Layout';
+import {MultiSelector} from '@astryxdesign/core/MultiSelector';
+
+export default function MultiSelectorGhostToolbar() {
+ const [columns, setColumns] = useState<string[]>(['Name', 'Email']);
+ const [filters, setFilters] = useState<string[]>(['Active']);
+
+ return (
+ <HStack align="center" gap={2}>
+ <Button label="Refresh" variant="ghost" />
+ <MultiSelector
+ label="Columns"
+ isLabelHidden
+ variant="ghost"
+ options={['Name', 'Email', 'Role', 'Status', 'Created']}
+ value={columns}
+ onChange={setColumns}
+ triggerDisplay="labels"
+ placeholder="Columns"
+ />
+ <MultiSelector
+ label="Status"
+ isLabelHidden
+ variant="ghost"
+ options={['Active', 'Inactive', 'Pending', 'Archived']}
+ value={filters}
+ onChange={setFilters}
+ triggerDisplay="labels"
+ placeholder="Status"
+ status={{type: 'warning', message: 'Some filters hide archived rows'}}
+ statusVariant="tooltip"
+ />
+ <Button label="Export" variant="ghost" />
+ </HStack>
+ );
+}
diff --git a/packages/cli/assets/templates/blocks/components/Selector/SelectorGhostToolbar.doc.mjs b/packages/cli/assets/templates/blocks/components/Selector/SelectorGhostToolbar.doc.mjs
new file mode 100644
index 0000000000..7f743c8b21
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Selector/SelectorGhostToolbar.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Selector',
+ name: 'Selector — Ghost Toolbar',
+ displayName: 'Selector — Ghost Toolbar',
+ description:
+ 'Borderless Selector variant composed with ghost buttons in a toolbar.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Selector', 'Button', 'HStack'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Selector/SelectorGhostToolbar.tsx b/packages/cli/assets/templates/blocks/components/Selector/SelectorGhostToolbar.tsx
new file mode 100644
index 0000000000..14edd78f5d
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Selector/SelectorGhostToolbar.tsx
@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Button} from '@astryxdesign/core/Button';
+import {HStack} from '@astryxdesign/core/Layout';
+import {Selector} from '@astryxdesign/core/Selector';
+
+export default function SelectorGhostToolbar() {
+ const [view, setView] = useState<string | undefined>('week');
+ const [density, setDensity] = useState<string | undefined>('comfortable');
+
+ return (
+ <HStack align="center" gap={2}>
+ <Button label="Today" variant="ghost" />
+ <Selector
+ label="Calendar view"
+ isLabelHidden
+ variant="ghost"
+ options={[
+ {value: 'day', label: 'Day'},
+ {value: 'week', label: 'Week'},
+ {value: 'month', label: 'Month'},
+ ]}
+ value={view}
+ onChange={setView}
+ />
+ <Selector
+ label="Density"
+ isLabelHidden
+ variant="ghost"
+ options={[
+ {value: 'compact', label: 'Compact'},
+ {value: 'comfortable', label: 'Comfortable'},
+ {value: 'spacious', label: 'Spacious'},
+ ]}
+ value={density}
+ onChange={setDensity}
+ status={{type: 'warning', message: 'This setting affects all users'}}
+ statusVariant="tooltip"
+ />
+ <Button label="Export" variant="ghost" />
+ </HStack>
+ );
+}
diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
index 7b9e9ddb79..193b951594 100644
--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs
+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
@@ -20,7 +20,10 @@ export const docs = {
],
theming: {
targets: [
- {className: 'astryx-multi-selector', visualProps: ['size', 'status']},
+ {
+ className: 'astryx-multi-selector',
+ visualProps: ['variant', 'size', 'status'],
+ },
{className: 'astryx-multi-selector-clear-icon'},
{
className: 'astryx-multi-selector-indicator-icon',
@@ -77,6 +80,13 @@ export const docs = {
description: 'Size variant for the selector.',
default: "'md'",
},
+ {
+ name: 'variant',
+ type: "'input' | 'ghost'",
+ description:
+ 'Visual trigger style. input is the bordered input treatment for forms; ghost is borderless and matches ghost buttons for toolbar usage.',
+ default: "'input'",
+ },
{
name: 'triggerDisplay',
type: "'count' | 'labels' | 'badges'",
@@ -162,10 +172,11 @@ export const docs = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
- default: "'attached'",
+ 'How the status message is placed relative to the input. attached overlaps directly below the bordered input and is only valid for the input variant; ghost selectors detach attached status messages by default. Use tooltip for compact toolbar controls.',
+ default:
+ "'attached' for input selectors; 'detached' for ghost selectors",
},
{
name: 'renderOption',
@@ -217,6 +228,11 @@ export const docs = {
description:
'Use inside InputGroup only when the control needs a short prefix or suffix addon as part of one decorated input surface; prefer count or labels trigger display so the group stays single-line.',
},
+ {
+ guidance: true,
+ description:
+ 'Use variant="ghost" when a multi-selector sits in a toolbar with ghost buttons. If validation status is needed there, prefer statusVariant="tooltip" so the toolbar height stays compact.',
+ },
{
guidance: false,
description: 'Use for single-value selection; use Selector instead.',
@@ -268,7 +284,8 @@ export const docsZh = {
isRequired: '将字段标记为必填。',
isLoading: '在触发器中显示加载旋转器。',
status: '带可选消息的验证状态。',
- statusVariant: '状态消息的放置方式:attached 直接叠加在输入框下方;detached 作为独立元素浮于下方并留有间距。',
+ statusVariant:
+ '状态消息的放置方式:attached 直接叠加在输入框下方;detached 作为独立元素浮于下方并留有间距。',
renderOption:
'每个可选选项的自定义渲染函数。不会用于分隔线、分组或全选行。',
xstyle: '布局自定义的 StyleX 样式,必须是 stylex.create() 值。',
@@ -349,6 +366,11 @@ export const docsDense = {
description:
'Use inside InputGroup only for a short prefix or suffix addon; prefer count or labels trigger display so the group stays single-line.',
},
+ {
+ guidance: true,
+ description:
+ 'Use variant="ghost" in toolbars with ghost buttons; prefer statusVariant="tooltip" for compact validation status.',
+ },
{
guidance: false,
description: 'Use for single-value selection; use Selector instead.',
@@ -378,6 +400,8 @@ export const docsDense = {
changeAction: 'async; fires after onChange',
placeholder: 'text when nothing selected',
size: 'size variant',
+ variant:
+ 'visual trigger style: input bordered control or ghost toolbar control',
triggerDisplay: 'how to show selected in trigger',
maxBadges: 'max badges before "+N"; badges mode only',
hasSelectAll: 'show select-all checkbox',
@@ -394,7 +418,8 @@ export const docsDense = {
isRequired: 'marks required',
isLoading: 'spinner in trigger',
status: 'validation status w/ optional message',
- statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
+ statusVariant:
+ 'status message placement; ghost detaches attached by default; use tooltip for compact toolbars.',
renderOption:
'custom render fn per selectable option; not dividers/sections/select-all',
xstyle: 'StyleX layout styles; stylex.create() only',
diff --git a/packages/core/src/MultiSelector/MultiSelector.test.tsx b/packages/core/src/MultiSelector/MultiSelector.test.tsx
index e4e037fd87..a939958608 100644
--- a/packages/core/src/MultiSelector/MultiSelector.test.tsx
+++ b/packages/core/src/MultiSelector/MultiSelector.test.tsx
@@ -1458,6 +1458,51 @@ describe('MultiSelector statusVariant forwarding', () => {
container.querySelector('.astryx-multi-selector-indicator-icon'),
).not.toBeNull();
});
+
+ it('detaches attached status by default for the ghost variant', () => {
+ const {container} = render(
+ <MultiSelector
+ label="Fruit"
+ options={['Apple', 'Banana']}
+ value={[]}
+ onChange={() => {}}
+ variant="ghost"
+ status={{type: 'error', message: 'Required'}}
+ />,
+ );
+ expect(container.querySelector('.astryx-multi-selector')).toHaveAttribute(
+ 'data-variant',
+ 'ghost',
+ );
+ expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+ 'data-variant',
+ 'detached',
+ );
+ });
+
+ it('uses a status tooltip for ghost multi-selectors when requested', () => {
+ const {container} = render(
+ <MultiSelector
+ label="Fruit"
+ options={['Apple', 'Banana']}
+ value={[]}
+ onChange={() => {}}
+ variant="ghost"
+ status={{type: 'warning', message: 'Some rows are hidden'}}
+ statusVariant="tooltip"
+ />,
+ );
+ expect(container.querySelector('.astryx-field-status')).toBeNull();
+ const statusButton = screen.getByRole('button', {
+ name: /warning details/i,
+ });
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(tooltip).toHaveTextContent('Some rows are hidden');
+ expect(statusButton.getAttribute('aria-describedby')).toContain(tooltip.id);
+ expect(
+ screen.getByRole('combobox').getAttribute('aria-describedby'),
+ ).toContain(tooltip.id);
+ });
});
describe('MultiSelector clear icon theme target', () => {
diff --git a/packages/core/src/MultiSelector/MultiSelector.tsx b/packages/core/src/MultiSelector/MultiSelector.tsx
index 07e943a7bc..0568f65d3d 100644
--- a/packages/core/src/MultiSelector/MultiSelector.tsx
+++ b/packages/core/src/MultiSelector/MultiSelector.tsx
@@ -177,6 +177,47 @@ const styles = stylex.create({
triggerIconStatus: {
transition: 'none',
},
+ triggerGhost: {
+ width: 'auto',
+ borderWidth: 0,
+ backgroundColor: 'transparent',
+ backgroundImage: {
+ default: null,
+ ':hover': {
+ '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
+ },
+ ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
+ },
+ boxShadow: {
+ default: 'none',
+ ':hover:not(:focus-within)': {
+ '@media (hover: hover)': 'none',
+ },
+ ':focus-within': 'none',
+ },
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ outline: {
+ default: 'none',
+ ':has(:focus-visible)': `2px solid ${colorVars['--color-accent']}`,
+ },
+ outlineOffset: {
+ default: '0',
+ ':has(:focus-visible)': '3px',
+ },
+ transitionProperty:
+ 'background-image, background-color, color, opacity, transform',
+ transform: {
+ default: 'scale(1)',
+ ':active': 'scale(0.98)',
+ },
+ },
+ triggerGhostDisabled: {
+ backgroundImage: 'none',
+ transform: {
+ default: 'none',
+ ':active': 'none',
+ },
+ },
// Clear button
clearButton: {
@@ -196,6 +237,24 @@ const styles = stylex.create({
},
outlineOffset: 1,
},
+ statusButton: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ padding: 0,
+ margin: 0,
+ borderWidth: 0,
+ borderStyle: 'none',
+ backgroundColor: 'transparent',
+ color: 'inherit',
+ cursor: 'pointer',
+ borderRadius: radiusVars['--radius-element'],
+ outline: {
+ default: 'none',
+ ':focus-visible': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,
+ },
+ outlineOffset: 1,
+ },
// Dropdown container
dropdown: {
@@ -347,8 +406,16 @@ const STATUS_ICON_COLOR_MAP: Record<
success: 'success',
};
+const STATUS_BUTTON_LABEL_KEY: Record<MultiSelectorStatusType, string> = {
+ warning: '@astryx.input.statusButton.warning',
+ error: '@astryx.input.statusButton.error',
+ success: '@astryx.input.statusButton.success',
+};
+
export type MultiSelectorSize = 'sm' | 'md' | 'lg';
+export type MultiSelectorVariant = 'input' | 'ghost';
+
export type MultiSelectorStatusType = 'warning' | 'error' | 'success';
export type {MultiSelectorStatus};
@@ -460,15 +527,24 @@ export interface MultiSelectorProps<
*/
size?: MultiSelectorSize;
+ /**
+ * Visual style of the selector trigger.
+ * - 'input': bordered input-style trigger for forms
+ * - 'ghost': borderless trigger matching ghost buttons, for toolbars
+ * @default 'input'
+ */
+ variant?: MultiSelectorVariant;
+
/**
* Status indicator for the selector.
*/
status?: MultiSelectorStatus;
/**
* How the status message is placed relative to the input.
- * - 'attached': message overlaps directly below the input (bordered treatment)
+ * - 'attached': message overlaps directly below the bordered input (input variant only)
* - 'detached': message floats below as a separate element with spacing
- * @default 'attached'
+ * - 'tooltip': message is exposed from the on-field status icon
+ * @default 'attached' for input selectors; 'detached' for ghost selectors
*/
statusVariant?: FieldStatusVariant;
@@ -613,6 +689,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
isLoading = false,
placeholder: placeholderFromProps,
size: sizeProp,
+ variant = 'input',
status,
statusVariant = 'attached',
labelTooltip,
@@ -641,6 +718,11 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
const searchPlaceholder =
searchPlaceholderFromProps ?? t('@astryx.multiSelector.searchPlaceholder');
const size = useSize(sizeProp, 'md');
+ const effectiveStatusVariant =
+ variant === 'ghost' && statusVariant === 'attached'
+ ? 'detached'
+ : statusVariant;
+
const triggerId = useId();
const listboxId = useId();
const descriptionId = useId();
@@ -680,12 +762,21 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
focusTrigger: 'always',
isEnabled: showsDisabledMessage,
});
+ const statusTooltip = useTooltip({
+ placement: 'above',
+ isEnabled: effectiveStatusVariant === 'tooltip' && !!status?.message,
+ });
const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
inputLabelId,
[
description ? descriptionId : null,
- status?.message ? statusMessageId : null,
+ !inputGroup && effectiveStatusVariant !== 'tooltip' && status?.message
+ ? statusMessageId
+ : null,
+ effectiveStatusVariant === 'tooltip' && status?.message
+ ? statusTooltip.describedBy
+ : null,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
],
inputGroup,
@@ -1332,7 +1423,10 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
// The detached message box renders its own leading status icon, so the
// on-field icon would duplicate it — keep the chevron indicator instead.
- const showStatusIcon = status != null && statusVariant !== 'detached';
+ const showStatusIcon =
+ status != null && effectiveStatusVariant !== 'detached';
+ const showStatusTooltip =
+ status != null && effectiveStatusVariant === 'tooltip' && !!status.message;
const multiSelectorContent = (
<>
@@ -1347,16 +1441,27 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
onClick={onTriggerClick}
data-testid={testId}
{...mergeProps(
- themeProps('multi-selector', {size, status: status?.type ?? null}),
+ themeProps('multi-selector', {
+ variant,
+ size,
+ status: status?.type ?? null,
+ }),
stylex.props(
inputWrapperStyles.base,
styles.triggerContainer,
sizeStyles[size],
+ variant === 'ghost' && styles.triggerGhost,
isDisabled && inputWrapperStyles.disabled,
+ variant === 'ghost' && isDisabled && styles.triggerGhostDisabled,
optimisticValue.length === 0 && styles.triggerPlaceholder,
- status && inputStatusBorderStyles[status.type],
- status && !isDisabled && inputStatusHoverShadowStyles[status.type],
- inputGroup && groupStyles.inGroup,
+ variant !== 'ghost' &&
+ status &&
+ inputStatusBorderStyles[status.type],
+ variant !== 'ghost' &&
+ status &&
+ !isDisabled &&
+ inputStatusHoverShadowStyles[status.type],
+ variant !== 'ghost' && inputGroup && groupStyles.inGroup,
xstyle,
),
className,
@@ -1439,11 +1544,27 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
showStatusIcon && styles.triggerIconStatus,
)}>
{showStatusIcon ? (
- <Icon
- icon={STATUS_ICON_MAP[status.type]}
- size="sm"
- color={STATUS_ICON_COLOR_MAP[status.type]}
- />
+ showStatusTooltip ? (
+ <button
+ ref={statusTooltip.ref}
+ type="button"
+ aria-label={t(STATUS_BUTTON_LABEL_KEY[status.type])}
+ aria-describedby={statusTooltip.describedBy}
+ onClick={e => e.stopPropagation()}
+ {...stylex.props(styles.statusButton)}>
+ <Icon
+ icon={STATUS_ICON_MAP[status.type]}
+ size="sm"
+ color={STATUS_ICON_COLOR_MAP[status.type]}
+ />
+ </button>
+ ) : (
+ <Icon
+ icon={STATUS_ICON_MAP[status.type]}
+ size="sm"
+ color={STATUS_ICON_COLOR_MAP[status.type]}
+ />
+ )
) : (
<Icon
icon="chevronDown"
@@ -1480,6 +1601,8 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
},
)}
+ {showStatusTooltip && statusTooltip.renderTooltip(status?.message ?? '')}
+
{showsDisabledMessage &&
disabledMessageTooltip.renderTooltip(disabledMessage)}
</>
@@ -1508,7 +1631,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
}
: undefined
}
- statusVariant={statusVariant}
+ statusVariant={effectiveStatusVariant}
labelTooltip={labelTooltip}
width={width}>
{multiSelectorContent}
diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs
index c8df91ccb3..4a35914d41 100644
--- a/packages/core/src/Selector/Selector.doc.mjs
+++ b/packages/core/src/Selector/Selector.doc.mjs
@@ -21,7 +21,10 @@ export const docs = {
],
theming: {
targets: [
- {className: 'astryx-selector', visualProps: ['size', 'status']},
+ {
+ className: 'astryx-selector',
+ visualProps: ['variant', 'size', 'status'],
+ },
{className: 'astryx-selector-option'},
{className: 'astryx-selector-clear-icon'},
{className: 'astryx-selector-indicator-icon', states: ['state']},
@@ -84,6 +87,13 @@ export const docs = {
description: 'Size variant for the selector.',
default: "'md'",
},
+ {
+ name: 'variant',
+ type: "'input' | 'ghost'",
+ description:
+ 'Visual trigger style. input is the bordered input treatment for forms; ghost is borderless and matches ghost buttons for toolbar usage.',
+ default: "'input'",
+ },
{
name: 'isDisabled',
type: 'boolean',
@@ -132,10 +142,10 @@ export const docs = {
},
{
name: 'statusVariant',
- type: "'attached' | 'detached'",
+ type: "'attached' | 'detached' | 'tooltip'",
description:
- 'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
- default: "'attached'",
+ 'How the status message is placed relative to the input. attached overlaps directly below the bordered input and is only valid for the input variant; ghost selectors detach attached status messages by default. Use tooltip for compact toolbar controls.',
+ default: "'attached' for input selectors; 'detached' for ghost selectors",
},
{
name: 'renderOption',
@@ -186,6 +196,11 @@ export const docs = {
description:
'Use inside InputGroup only when the selector needs a short prefix or suffix addon as part of one decorated input surface.',
},
+ {
+ guidance: true,
+ description:
+ 'Use variant="ghost" when a selector sits in a toolbar with ghost buttons. If validation status is needed there, prefer statusVariant="tooltip" so the toolbar height stays compact.',
+ },
{
guidance: false,
description:
@@ -375,6 +390,11 @@ export const docsDense = {
description:
'Use inside InputGroup only when the selector needs a short prefix or suffix addon.',
},
+ {
+ guidance: true,
+ description:
+ 'Use variant="ghost" in toolbars with ghost buttons; prefer statusVariant="tooltip" for compact validation status.',
+ },
{
guidance: false,
description:
diff --git a/packages/core/src/Selector/Selector.test.tsx b/packages/core/src/Selector/Selector.test.tsx
index 778b075935..1b59e0561d 100644
--- a/packages/core/src/Selector/Selector.test.tsx
+++ b/packages/core/src/Selector/Selector.test.tsx
@@ -1271,6 +1271,47 @@ describe('Selector statusVariant forwarding', () => {
container.querySelector('.astryx-selector-indicator-icon'),
).not.toBeNull();
});
+
+ it('detaches attached status by default for the ghost variant', () => {
+ const {container} = render(
+ <Selector
+ label="Fruit"
+ options={['Apple', 'Banana']}
+ variant="ghost"
+ status={{type: 'error', message: 'Required'}}
+ />,
+ );
+ expect(container.querySelector('.astryx-selector')).toHaveAttribute(
+ 'data-variant',
+ 'ghost',
+ );
+ expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+ 'data-variant',
+ 'detached',
+ );
+ });
+
+ it('uses a status tooltip for ghost selectors when requested', () => {
+ const {container} = render(
+ <Selector
+ label="Fruit"
+ options={['Apple', 'Banana']}
+ variant="ghost"
+ status={{type: 'warning', message: 'Visible to all users'}}
+ statusVariant="tooltip"
+ />,
+ );
+ expect(container.querySelector('.astryx-field-status')).toBeNull();
+ const statusButton = screen.getByRole('button', {
+ name: /warning details/i,
+ });
+ const tooltip = screen.getByRole('tooltip', h);
+ expect(tooltip).toHaveTextContent('Visible to all users');
+ expect(statusButton.getAttribute('aria-describedby')).toContain(tooltip.id);
+ expect(
+ screen.getByRole('combobox').getAttribute('aria-describedby'),
+ ).toContain(tooltip.id);
+ });
});
describe('Selector clear icon theme target', () => {
diff --git a/packages/core/src/Selector/Selector.tsx b/packages/core/src/Selector/Selector.tsx
index 6a483342c3..dee927d5f5 100644
--- a/packages/core/src/Selector/Selector.tsx
+++ b/packages/core/src/Selector/Selector.tsx
@@ -154,6 +154,47 @@ const styles = stylex.create({
// Disable rotation transition for status icons
transition: 'none',
},
+ triggerGhost: {
+ width: 'auto',
+ borderWidth: 0,
+ backgroundColor: 'transparent',
+ backgroundImage: {
+ default: null,
+ ':hover': {
+ '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
+ },
+ ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
+ },
+ boxShadow: {
+ default: 'none',
+ ':hover:not(:focus-within)': {
+ '@media (hover: hover)': 'none',
+ },
+ ':focus-within': 'none',
+ },
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ outline: {
+ default: 'none',
+ ':has(:focus-visible)': `2px solid ${colorVars['--color-accent']}`,
+ },
+ outlineOffset: {
+ default: '0',
+ ':has(:focus-visible)': '3px',
+ },
+ transitionProperty:
+ 'background-image, background-color, color, opacity, transform',
+ transform: {
+ default: 'scale(1)',
+ ':active': 'scale(0.98)',
+ },
+ },
+ triggerGhostDisabled: {
+ backgroundImage: 'none',
+ transform: {
+ default: 'none',
+ ':active': 'none',
+ },
+ },
// Clear button
clearButton: {
@@ -173,6 +214,24 @@ const styles = stylex.create({
},
outlineOffset: 1,
},
+ statusButton: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ padding: 0,
+ margin: 0,
+ borderWidth: 0,
+ borderStyle: 'none',
+ backgroundColor: 'transparent',
+ color: 'inherit',
+ cursor: 'pointer',
+ borderRadius: radiusVars['--radius-element'],
+ outline: {
+ default: 'none',
+ ':focus-visible': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,
+ },
+ outlineOffset: 1,
+ },
// Dropdown container
dropdown: {
@@ -309,8 +368,16 @@ const STATUS_ICON_COLOR_MAP: Record<
success: 'success',
};
+const STATUS_BUTTON_LABEL_KEY: Record<SelectorStatusType, string> = {
+ warning: '@astryx.input.statusButton.warning',
+ error: '@astryx.input.statusButton.error',
+ success: '@astryx.input.statusButton.success',
+};
+
export type SelectorSize = 'sm' | 'md' | 'lg';
+export type SelectorVariant = 'input' | 'ghost';
+
export type SelectorStatusType = 'warning' | 'error' | 'success';
export interface SelectorStatus {
@@ -411,6 +478,14 @@ interface SelectorPropsBase<
*/
size?: SelectorSize;
+ /**
+ * Visual style of the selector trigger.
+ * - 'input': bordered input-style trigger for forms
+ * - 'ghost': borderless trigger matching ghost buttons, for toolbars
+ * @default 'input'
+ */
+ variant?: SelectorVariant;
+
/**
* Status indicator for the selector.
* When set, displays a colored border and status icon.
@@ -419,9 +494,10 @@ interface SelectorPropsBase<
status?: SelectorStatus;
/**
* How the status message is placed relative to the input.
- * - 'attached': message overlaps directly below the input (bordered treatment)
+ * - 'attached': message overlaps directly below the bordered input (input variant only)
* - 'detached': message floats below as a separate element with spacing
- * @default 'attached'
+ * - 'tooltip': message is exposed from the on-field status icon
+ * @default 'attached' for input selectors; 'detached' for ghost selectors
*/
statusVariant?: FieldStatusVariant;
@@ -590,6 +666,7 @@ export function Selector<T extends SelectorOptionType>(
isLoading = false,
placeholder: placeholderFromProps,
size: sizeProp,
+ variant = 'input',
status,
statusVariant = 'attached',
labelTooltip,
@@ -613,6 +690,10 @@ export function Selector<T extends SelectorOptionType>(
searchPlaceholderFromProps ?? t('@astryx.selector.searchPlaceholder');
const hasClear = hasClearProp === true;
const size = useSize(sizeProp, 'md');
+ const effectiveStatusVariant =
+ variant === 'ghost' && statusVariant === 'attached'
+ ? 'detached'
+ : statusVariant;
// Normalize null to undefined for internal use (null is the clear sentinel)
const normalizedValue = value === null ? undefined : value;
@@ -648,12 +729,21 @@ export function Selector<T extends SelectorOptionType>(
focusTrigger: 'always',
isEnabled: showsDisabledMessage,
});
+ const statusTooltip = useTooltip({
+ placement: 'above',
+ isEnabled: effectiveStatusVariant === 'tooltip' && !!status?.message,
+ });
const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
inputLabelId,
[
description ? descriptionId : null,
- status?.message ? statusMessageId : null,
+ !inputGroup && effectiveStatusVariant !== 'tooltip' && status?.message
+ ? statusMessageId
+ : null,
+ effectiveStatusVariant === 'tooltip' && status?.message
+ ? statusTooltip.describedBy
+ : null,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
],
inputGroup,
@@ -1051,7 +1141,10 @@ export function Selector<T extends SelectorOptionType>(
// The detached message box renders its own leading status icon, so the
// on-field icon would duplicate it — keep the chevron indicator instead.
- const showStatusIcon = status != null && statusVariant !== 'detached';
+ const showStatusIcon =
+ status != null && effectiveStatusVariant !== 'detached';
+ const showStatusTooltip =
+ status != null && effectiveStatusVariant === 'tooltip' && !!status.message;
const selectorContent = (
<>
@@ -1066,16 +1159,27 @@ export function Selector<T extends SelectorOptionType>(
onClick={onTriggerClick}
data-testid={testId}
{...mergeProps(
- themeProps('selector', {size, status: status?.type ?? null}),
+ themeProps('selector', {
+ variant,
+ size,
+ status: status?.type ?? null,
+ }),
stylex.props(
inputWrapperStyles.base,
styles.triggerContainer,
sizeStyles[size],
+ variant === 'ghost' && styles.triggerGhost,
isDisabled && inputWrapperStyles.disabled,
+ variant === 'ghost' && isDisabled && styles.triggerGhostDisabled,
!selectedItem && styles.triggerPlaceholder,
- status && inputStatusBorderStyles[status.type],
- status && !isDisabled && inputStatusHoverShadowStyles[status.type],
- inputGroup && groupStyles.inGroup,
+ variant !== 'ghost' &&
+ status &&
+ inputStatusBorderStyles[status.type],
+ variant !== 'ghost' &&
+ status &&
+ !isDisabled &&
+ inputStatusHoverShadowStyles[status.type],
+ variant !== 'ghost' && inputGroup && groupStyles.inGroup,
xstyle,
),
className,
@@ -1157,11 +1261,27 @@ export function Selector<T extends SelectorOptionType>(
showStatusIcon && styles.triggerIconStatus,
)}>
{showStatusIcon ? (
- <Icon
- icon={STATUS_ICON_MAP[status.type]}
- size="sm"
- color={STATUS_ICON_COLOR_MAP[status.type]}
- />
+ showStatusTooltip ? (
+ <button
+ ref={statusTooltip.ref}
+ type="button"
+ aria-label={t(STATUS_BUTTON_LABEL_KEY[status.type])}
+ aria-describedby={statusTooltip.describedBy}
+ onClick={e => e.stopPropagation()}
+ {...stylex.props(styles.statusButton)}>
+ <Icon
+ icon={STATUS_ICON_MAP[status.type]}
+ size="sm"
+ color={STATUS_ICON_COLOR_MAP[status.type]}
+ />
+ </button>
+ ) : (
+ <Icon
+ icon={STATUS_ICON_MAP[status.type]}
+ size="sm"
+ color={STATUS_ICON_COLOR_MAP[status.type]}
+ />
+ )
) : (
<Icon
icon="chevronDown"
@@ -1214,6 +1334,8 @@ export function Selector<T extends SelectorOptionType>(
},
)}
+ {showStatusTooltip && statusTooltip.renderTooltip(status?.message ?? '')}
+
{showsDisabledMessage &&
disabledMessageTooltip.renderTooltip(disabledMessage)}
</>
@@ -1242,7 +1364,7 @@ export function Selector<T extends SelectorOptionType>(
}
: undefined
}
- statusVariant={statusVariant}
+ statusVariant={effectiveStatusVariant}
labelTooltip={labelTooltip}
width={width}>
{selectorContent}