CardSelect

beta

The CardSelect component provides an accessible and customizable card-based selection interface. It supports both single and multiple selection modes with flexible layouts (horizontal, vertical, or grid), making it suitable for forms, settings, and decision workflows.

Usage

import { CardSelect } from "@harnessio/ui/components";

// ...

return (
  <CardSelect.Root type="single">
    <CardSelect.Item value="option-1" icon="git-branch">
      <CardSelect.Title>Option 1</CardSelect.Title>
      <CardSelect.Description>With an icon</CardSelect.Description>
    </CardSelect.Item>

    <CardSelect.Item value="option-2" logo="jira">
      <CardSelect.Title>Option 2</CardSelect.Title>
      <CardSelect.Description>With a logo</CardSelect.Description>
    </CardSelect.Item>
  </CardSelect.Root>
)

Selection Modes

The CardSelect supports two selection types:

Layout

Cards can be arranged horizontally, vertically, or in a grid:

Gap

Control the gap between cards using the gap prop:

Icons and Logos

Cards can display either an icon or a logo:

Disabled

Cards can be disabled either individually or as a group:

API Reference

Root

The CardSelect.Root is the top-level wrapper that controls selection state.

<CardSelect.Root
  type="single"                     // Required: 'single' or 'multiple'
  value={selectedValue}             // [OPTIONAL] For controlled usage
  defaultValue={defaultValue}       // [OPTIONAL] For selecting item initially
  onValueChange={handleChange}      // [OPTIONAL] Selection change handler
  layout="horizontal"               // [OPTIONAL] Card layout: 'horizontal', 'vertical', or 'grid'
  gap="md"                          // [OPTIONAL] Space between cards
  disabled={false}                  // [OPTIONAL] Disable all selections
>
  {/* CardSelect.Item components */}
</CardSelect.Root>

Prop	Required	Default	Type
type	true		'single' \| 'multiple'
value	false	undefined \| []	unknown \| unknown[]
defaultValue	false	undefined	unknown \| unknown[]
onValueChange	false	undefined	(val: unknown) => void \| (val: unknown[]) => void
layout	false	'vertical'	'horizontal' \| 'vertical' \| 'grid'
gap	false	'md'	'sm' \| 'md' \| 'lg'
rows	false	undefined	number
cols	false	undefined	number
disabled	false	false	boolean

Item

Represents an individual selectable card option.

<CardSelect.Item
  value="unique-id"               // Required: Unique identifier
  icon="git-branch"                  // [OPTIONAL] Icon to display
  logo="gitlab"                  // [OPTIONAL] Logo instead of icon
  disabled={false}               // [OPTIONAL] Disable this item
>
  {/* CardSelect.Title and CardSelect.Description */}
</CardSelect.Item>

Prop	Required	Default	Type
value	true		string
icon	false		string
logo	false		string
disabled	false	false	boolean

Title

Displays the main heading for a card item.

<CardSelect.Title>
  Option Title
</CardSelect.Title>

Prop	Required	Default	Type
children	true		ReactNode

Description

Provides additional details for a card item.

Prop	Required	Default	Type
children	true		ReactNode