feat(select): add isClearable

.changeset/olive-buckets-own.md

@@ -0,0 +1,6 @@
+---
+"@nextui-org/select": patch
+"@nextui-org/theme": patch
+---
+
+add `isClearable` and `onClear` prop to Select component (#2239)

apps/docs/content/components/select/index.ts

@@ -27,6 +27,7 @@ import multipleControlledOnChange from "./multiple-controlled-onchange";
 import multipleWithChips from "./multiple-chips";
 import customSelectorIcon from "./custom-selector-icon";
 import customStyles from "./custom-styles";
+import isClearable from "./is-clearable";
 
 export const selectContent = {
   usage,
@@ -58,4 +59,5 @@ export const selectContent = {
   multipleWithChips,
   customSelectorIcon,
   customStyles,
+  isClearable,
 };

apps/docs/content/components/select/is-clearable.raw.jsx

@@ -0,0 +1,65 @@
+import {Select, SelectItem} from "@nextui-org/react";
+
+export const animals = [
+  {key: "cat", label: "Cat"},
+  {key: "dog", label: "Dog"},
+  {key: "elephant", label: "Elephant"},
+  {key: "lion", label: "Lion"},
+  {key: "tiger", label: "Tiger"},
+  {key: "giraffe", label: "Giraffe"},
+  {key: "dolphin", label: "Dolphin"},
+  {key: "penguin", label: "Penguin"},
+  {key: "zebra", label: "Zebra"},
+  {key: "shark", label: "Shark"},
+  {key: "whale", label: "Whale"},
+  {key: "otter", label: "Otter"},
+  {key: "crocodile", label: "Crocodile"},
+];
+
+export const PetBoldIcon = (props) => {
+  return (
+    <svg
+      aria-hidden="true"
+      fill="none"
+      focusable="false"
+      height="1em"
+      role="presentation"
+      viewBox="0 0 24 24"
+      width="1em"
+      {...props}
+    >
+      <path
+        d="M19.0803 15.7203C18.4903 12.1903 15.1003 9.32031 11.5203 9.32031C7.63028 9.32031 4.21028 12.4703 3.88028 16.3503C3.75028 17.8503 4.23028 19.2703 5.22028 20.3403C6.20028 21.4103 7.58028 22.0003 9.08028 22.0003H13.7603C15.4503 22.0003 16.9303 21.3403 17.9403 20.1503C18.9503 18.9603 19.3503 17.3803 19.0803 15.7203Z"
+        fill="currentColor"
+      />
+      <path
+        d="M10.2796 7.86C11.8978 7.86 13.2096 6.54819 13.2096 4.93C13.2096 3.31181 11.8978 2 10.2796 2C8.66141 2 7.34961 3.31181 7.34961 4.93C7.34961 6.54819 8.66141 7.86 10.2796 7.86Z"
+        fill="currentColor"
+      />
+      <path
+        d="M16.94 9.02844C18.2876 9.02844 19.38 7.93601 19.38 6.58844C19.38 5.24086 18.2876 4.14844 16.94 4.14844C15.5924 4.14844 14.5 5.24086 14.5 6.58844C14.5 7.93601 15.5924 9.02844 16.94 9.02844Z"
+        fill="currentColor"
+      />
+      <path
+        d="M20.5496 12.9313C21.6266 12.9313 22.4996 12.0582 22.4996 10.9812C22.4996 9.90429 21.6266 9.03125 20.5496 9.03125C19.4727 9.03125 18.5996 9.90429 18.5996 10.9812C18.5996 12.0582 19.4727 12.9313 20.5496 12.9313Z"
+        fill="currentColor"
+      />
+      <path
+        d="M3.94 10.9816C5.28757 10.9816 6.38 9.88914 6.38 8.54156C6.38 7.19399 5.28757 6.10156 3.94 6.10156C2.59243 6.10156 1.5 7.19399 1.5 8.54156C1.5 9.88914 2.59243 10.9816 3.94 10.9816Z"
+        fill="currentColor"
+      />
+    </svg>
+  );
+};
+
+export default function App() {
+  return (
+    <div className="flex w-screen justify-center items-center">
+      <Select className="max-w-xs my-5" isClearable={true} label="Favorite Animal">
+        {animals.map((animal) => (
+          <SelectItem key={animal.key}>{animal.label}</SelectItem>
+        ))}
+      </Select>
+    </div>
+  );
+}

apps/docs/content/components/select/is-clearable.ts

@@ -0,0 +1,9 @@
+import App from "./is-clearable.raw.jsx?raw";
+
+const react = {
+  "/App.jsx": App,
+};
+
+export default {
+  ...react,
+};

apps/docs/content/docs/components/select.mdx

@@ -148,6 +148,12 @@ You can combine the `isInvalid` and `errorMessage` properties to show an invalid
 
 <CodeDemo title="With Error Message" files={selectContent.errorMessage} />
 
+### Clear Button
+
+If you pass the `isClearable` property to the select, it will have a clear button which will be visible only when a value is selected.
+
+<CodeDemo title="Clear Button" files={selectContent.isClearable} />
+
 ### Controlled
 
 You can use the `selectedKeys` and `onSelectionChange` / `onChange` properties to control the select value.
@@ -383,6 +389,7 @@ the popover and listbox components.
 | isDisabled                  | `boolean`                                                                                                                                                                                                              | Whether the select is disabled.                                                                                        | `false`            |
 | isMultiline                 | `boolean`                                                                                                                                                                                                              | Whether the select should allow multiple lines of text.                                                                | `false`            |
 | isInvalid                   | `boolean`                                                                                                                                                                                                              | Whether the select is invalid.                                                                                         | `false`            |
+| isClearable                 | `boolean`                                                                                                                                                                                                              | Whether the select should have a clear button.                                                                         | `false`            |
 | validationState             | `valid` \| `invalid`                                                                                                                                                                                                   | Whether the select should display its "valid" or "invalid" visual styling. (**Deprecated**) use **isInvalid** instead. | -                  |
 | showScrollIndicators        | `boolean`                                                                                                                                                                                                              | Whether the select should show scroll indicators when the listbox is scrollable.                                       | `true`             |
 | autoFocus                   | `boolean`                                                                                                                                                                                                              | Whether the select should be focused on the first mount.                                                               | `false`            |
@@ -403,7 +410,7 @@ the popover and listbox components.
 | onSelectionChange | `(keys: "all" \| Set<React.Key> & {anchorKey?: string; currentKey?: string}) => void`                 | Callback fired when the selected keys change.                                        |
 | onChange          | `React.ChangeEvent<HTMLSelectElement>`        | Native select change event, fired when the selected value changes.                   |
 | renderValue       | [RenderValueFunction](#render-value-function) | Function to render the value of the select. It renders the selected item by default. |
-
+| onClear           | `() => void`                                  | Handler that is called when the clear button is clicked.
 ---
 
 ### SelectItem Props

packages/components/select/src/select.tsx

@@ -1,6 +1,6 @@
 import {Listbox} from "@nextui-org/listbox";
 import {FreeSoloPopover} from "@nextui-org/popover";
-import {ChevronDownIcon} from "@nextui-org/shared-icons";
+import {ChevronDownIcon, CloseFilledIcon} from "@nextui-org/shared-icons";
 import {Spinner} from "@nextui-org/spinner";
 import {forwardRef} from "@nextui-org/system";
 import {ScrollShadow} from "@nextui-org/scroll-shadow";
@@ -29,8 +29,10 @@ function Select<T extends object>(props: Props<T>, ref: ForwardedRef<HTMLSelectE
     endContent,
     placeholder,
     renderValue,
+    isClearable,
     shouldLabelBeOutside,
     disableAnimation,
+    getClearButtonProps,
     getBaseProps,
     getLabelProps,
     getTriggerProps,
@@ -52,6 +54,27 @@ function Select<T extends object>(props: Props<T>, ref: ForwardedRef<HTMLSelectE
 
   const clonedIcon = cloneElement(selectorIcon as ReactElement, getSelectorIconProps());
 
+  const clearButton = useMemo(() => {
+    if (isClearable && state.selectedItems?.length) {
+      return <button {...getClearButtonProps()}>{<CloseFilledIcon />}</button>;
+    }
+
+    return null;
+  }, [isClearable, getClearButtonProps, state.selectedItems?.length]);
+
+  const end = useMemo(() => {
+    if (clearButton) {
+      return (
+        <div className="flex end-18">
+          {clearButton}
+          {endContent && <span className="ms-3">{endContent}</span>}
+        </div>
+      );
+    }
+
+    return endContent && <span className="mb-4">{endContent}</span>;
+  }, [clearButton, endContent]);
+
   const helperWrapper = useMemo(() => {
     const shouldShowError = isInvalid && errorMessage;
     const hasContent = shouldShowError || description;
@@ -130,7 +153,7 @@ function Select<T extends object>(props: Props<T>, ref: ForwardedRef<HTMLSelectE
             {endContent && state.selectedItems && (
               <VisuallyHidden elementType="span">,</VisuallyHidden>
             )}
-            {endContent}
+            {end}
           </div>
           {renderIndicator}
         </Component>

packages/components/select/src/use-select.ts

@@ -17,7 +17,7 @@ import {useAriaButton} from "@nextui-org/use-aria-button";
 import {useFocusRing} from "@react-aria/focus";
 import {clsx, dataAttr, objectToDeps} from "@nextui-org/shared-utils";
 import {mergeProps} from "@react-aria/utils";
-import {useHover} from "@react-aria/interactions";
+import {useHover, usePress} from "@react-aria/interactions";
 import {PopoverProps} from "@nextui-org/popover";
 import {ScrollShadowProps} from "@nextui-org/scroll-shadow";
 import {
@@ -133,6 +133,11 @@ interface Props<T> extends Omit<HTMLNextUIProps<"select">, keyof SelectVariantPr
    * Handler that is called when the selection changes.
    */
   onSelectionChange?: (keys: SharedSelection) => void;
+  /**
+   * Callback fired when the value is cleared.
+   * if you pass this prop, the clear button will be shown.
+   */
+  onClear?: () => void;
 }
 
 interface SelectData {
@@ -187,6 +192,7 @@ export function useSelect<T extends object>(originalProps: UseSelectProps<T>) {
     validationState,
     onChange,
     onClose,
+    onClear,
     className,
     classNames,
     ...otherProps
@@ -297,11 +303,24 @@ export function useSelect<T extends object>(originalProps: UseSelectProps<T>) {
     triggerRef,
   );
 
+  const handleClear = useCallback(() => {
+    state.setSelectedKeys(new Set([]));
+    onClear?.();
+    domRef.current?.focus();
+  }, [onClear, state]);
+
+  const {pressProps: clearPressProps} = usePress({
+    isDisabled: !!originalProps?.isDisabled,
+    onPress: handleClear,
+  });
+
   const isInvalid = originalProps.isInvalid || validationState === "invalid" || isAriaInvalid;
 
   const {isPressed, buttonProps} = useAriaButton(triggerProps, triggerRef);
 
   const {focusProps, isFocused, isFocusVisible} = useFocusRing();
+  const {focusProps: clearFocusProps, isFocusVisible: isClearButtonFocusVisible} = useFocusRing();
+
   const {isHovered, hoverProps} = useHover({isDisabled: originalProps.isDisabled});
 
   const labelPlacement = useMemo<SelectVariantProps["labelPlacement"]>(() => {
@@ -319,6 +338,7 @@ export function useSelect<T extends object>(originalProps: UseSelectProps<T>) {
       (!(hasPlaceholder || !!description) || !!originalProps.isMultiline));
   const shouldLabelBeInside = labelPlacement === "inside";
   const isOutsideLeft = labelPlacement === "outside-left";
+  const isClearable = originalProps.isClearable;
 
   const isFilled =
     state.isOpen ||
@@ -337,11 +357,19 @@ export function useSelect<T extends object>(originalProps: UseSelectProps<T>) {
       select({
         ...variantProps,
         isInvalid,
+        isClearable,
         labelPlacement,
         disableAnimation,
         className,
       }),
-    [objectToDeps(variantProps), isInvalid, labelPlacement, disableAnimation, className],
+    [
+      objectToDeps(variantProps),
+      isClearable,
+      isInvalid,
+      labelPlacement,
+      disableAnimation,
+      className,
+    ],
   );
 
   // scroll the listbox to the selected item
@@ -636,6 +664,22 @@ export function useSelect<T extends object>(originalProps: UseSelectProps<T>) {
     [slots, spinnerRef, spinnerProps, classNames?.spinner],
   );
 
+  const getClearButtonProps: PropGetter = useCallback(
+    (props = {}) => {
+      return {
+        ...props,
+        role: "button",
+        tabIndex: -1,
+        "aria-label": "clear selection",
+        "data-slot": "clear-button",
+        "data-focus-visible": dataAttr(isClearButtonFocusVisible),
+        className: slots.clearButton({class: clsx(classNames?.clearButton, props?.className)}),
+        ...mergeProps(clearPressProps, clearFocusProps),
+      };
+    },
+    [slots, isClearButtonFocusVisible, clearPressProps, clearFocusProps, classNames?.clearButton],
+  );
+
   // store the data to be used in useHiddenSelect
   selectData.set(state, {
     isDisabled: originalProps?.isDisabled,
@@ -653,6 +697,7 @@ export function useSelect<T extends object>(originalProps: UseSelectProps<T>) {
     name,
     triggerRef,
     isLoading,
+    isClearable,
     placeholder,
     startContent,
     endContent,
@@ -671,6 +716,7 @@ export function useSelect<T extends object>(originalProps: UseSelectProps<T>) {
     errorMessage,
     getBaseProps,
     getTriggerProps,
+    getClearButtonProps,
     getLabelProps,
     getValueProps,
     getListboxProps,

packages/components/select/stories/select.stories.tsx

@@ -1043,3 +1043,11 @@ export const CustomStyles = {
     },
   },
 };
+
+export const Clearable = {
+  render: Template,
+  args: {
+    ...defaultProps,
+    isClearable: true,
+  },
+};

packages/core/theme/src/components/select.ts

@@ -29,6 +29,24 @@ const select = tv({
     listboxWrapper: "scroll-py-6 max-h-64 w-full",
     listbox: "",
     popoverContent: "w-full p-1 overflow-hidden",
+    clearButton: [
+      "w-4",
+      "h-4",
+      "z-10",
+      "mb-4",
+      "relative",
+      "start-auto",
+      "appearance-none",
+      "outline-none",
+      "select-none",
+      "opacity-70",
+      "hover:!opacity-100",
+      "cursor-pointer",
+      "active:!opacity-70",
+      "rounded-full",
+      // focus ring
+      ...dataFocusVisibleClasses,
+    ],
     helperWrapper: "p-1 flex relative flex-col gap-1.5",
     description: "text-tiny text-foreground-400",
     errorMessage: "text-tiny text-danger",
@@ -101,14 +119,17 @@ const select = tv({
         label: "text-tiny",
         trigger: "h-8 min-h-8 px-2 rounded-small",
         value: "text-small",
+        clearButton: "text-medium",
       },
       md: {
         trigger: "h-10 min-h-10 rounded-medium",
         value: "text-small",
+        clearButton: "text-large",
       },
       lg: {
         trigger: "h-12 min-h-12 rounded-large",
         value: "text-medium",
+        clearButton: "text-large",
       },
     },
     radius: {
@@ -149,6 +170,11 @@ const select = tv({
         base: "min-w-40",
       },
     },
+    isClearable: {
+      true: {
+        clearButton: "peer-data-[filled=true]:opacity-70 peer-data-[filled=true]:block",
+      },
+    },
     isDisabled: {
       true: {
         base: "opacity-disabled pointer-events-none",
@@ -196,6 +222,7 @@ const select = tv({
           "motion-reduce:transition-none",
         ],
         selectorIcon: "transition-transform duration-150 ease motion-reduce:transition-none",
+        clearButton: ["transition-opacity", "motion-reduce:transition-none"],
       },
     },
     disableSelectorIconRotation: {