# ChipGroup

A labelled set of chips, announced as one group rather than as loose controls.

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/controls/ChipGroup/ChipGroup.tsx

## Guidance

{
  "summary": "A labelled set of chips, announced as one group rather than as loose controls.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "A labelled set of chips. Without a group, a row of chips reads to assistive technology as loose\ncontrols with no relationship, and every call site ends up re-inventing the row layout."
    },
    {
      "heading": "Keep one kind per group",
      "body": "Chips carry their affordance in their shape, so a group holding both a selectable chip and a\nremovable one gives two different behaviors the same appearance.\n\nA marker that does nothing is a `Tag`. Keep it outside the group."
    },
    {
      "heading": "Selection stays with the caller",
      "body": "The group holds no selected state. Each `Chip` takes its own `selected` and `onPress`, so single\nselection and multiple selection both work without a second component."
    },
    {
      "heading": "Wrap or scroll",
      "body": "Wrapping is the default, and it is the right choice when the count comes from data. Reach for\n`scroll` only when the set is known and short.\n\nFor a fixed set of five or fewer mutually exclusive view modes, use `SegmentedControl` instead. The\nboundary is the shape of the set: a segmented control is fixed, connected, and equal-width, while a\nchip group grows and wraps."
    }
  ],
  "usage": [],
  "examples": [
    {
      "kind": "do",
      "caption": "Fill a group with selectable chips, or fill it with removable chips."
    },
    {
      "kind": "dont",
      "caption": "Mix the two, or make only some of the chips interactive."
    }
  ],
  "source": "packages/design-system/src/components/controls/ChipGroup/ChipGroup.mdx",
  "status": "local-preview",
  "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification."
}

## Contract and public API

```json
{
  "props": [
    {
      "name": "children",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": true,
      "description": "`Chip` children. Keep them one kind: all selectable, or all removable.",
      "source": {
        "path": "packages/design-system/src/components/controls/ChipGroup/ChipGroup.tsx",
        "line": 11
      }
    },
    {
      "name": "label",
      "type": "string",
      "declared_type": "string",
      "required": true,
      "description": "Accessible name for the group, announced before its chips.",
      "source": {
        "path": "packages/design-system/src/components/controls/ChipGroup/ChipGroup.tsx",
        "line": 13
      }
    },
    {
      "name": "scroll",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Scrolls horizontally on one line instead of wrapping onto several.",
      "source": {
        "path": "packages/design-system/src/components/controls/ChipGroup/ChipGroup.tsx",
        "line": 15
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/controls/ChipGroup/ChipGroup.tsx",
        "line": 16
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Selector for the group wrapper. Chips derive nothing from it; give each `Chip` its own.",
      "source": {
        "path": "packages/design-system/src/components/controls/ChipGroup/ChipGroup.tsx",
        "line": 18
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "ChipGroup",
    "public_path": "ChipGroup",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "ChipGroup",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/controls/ChipGroup/ChipGroup.tsx",
          "line": 24
        },
        "props_type": "ChipGroupProps",
        "props": [
          {
            "name": "children",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": true,
            "description": "`Chip` children. Keep them one kind: all selectable, or all removable.",
            "source": {
              "path": "packages/design-system/src/components/controls/ChipGroup/ChipGroup.tsx",
              "line": 11
            }
          },
          {
            "name": "label",
            "type": "string",
            "declared_type": "string",
            "required": true,
            "description": "Accessible name for the group, announced before its chips.",
            "source": {
              "path": "packages/design-system/src/components/controls/ChipGroup/ChipGroup.tsx",
              "line": 13
            }
          },
          {
            "name": "scroll",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Scrolls horizontally on one line instead of wrapping onto several.",
            "source": {
              "path": "packages/design-system/src/components/controls/ChipGroup/ChipGroup.tsx",
              "line": 15
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/controls/ChipGroup/ChipGroup.tsx",
              "line": 16
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Selector for the group wrapper. Chips derive nothing from it; give each `Chip` its own.",
            "source": {
              "path": "packages/design-system/src/components/controls/ChipGroup/ChipGroup.tsx",
              "line": 18
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/controls/ChipGroup/ChipGroup.tsx",
        "line": 9,
        "name": "ChipGroupProps",
        "code": "export interface ChipGroupProps {\n    /** `Chip` children. Keep them one kind: all selectable, or all removable. */\n    children: React.ReactNode;\n    /** Accessible name for the group, announced before its chips. */\n    label: string;\n    /** Scrolls horizontally on one line instead of wrapping onto several. */\n    scroll?: boolean;\n    className?: string;\n    /** Selector for the group wrapper. Chips derive nothing from it; give each `Chip` its own. */\n    testId?: string;\n}"
      }
    ],
    "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
  },
  "spec": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "ChipGroup",
      "status": "preview",
      "version": "1.0.0",
      "summary": "A labelled set of chips, announced as one group rather than as loose controls."
    },
    "parts": [
      {
        "id": "root",
        "label": "Root",
        "description": "Group container that owns the accessible name and the row layout.",
        "required": true
      },
      {
        "id": "chips",
        "label": "Chips",
        "description": "One kind of Chip: all selectable, or all removable.",
        "required": true
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "wrap": {
          "label": "Wrap",
          "description": "Chips flow onto more lines as the set grows."
        },
        "scroll": {
          "label": "Scroll",
          "description": "Chips stay on one line and the row scrolls horizontally."
        }
      },
      "sizes": {},
      "tones": {}
    },
    "variants": [
      {
        "id": "wrap",
        "label": "Wrap",
        "description": "Default. Chips wrap onto more lines.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      },
      {
        "id": "scroll",
        "label": "Scroll",
        "description": "One line with a hidden scrollbar, for a long known set.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [],
    "measurements": [
      {
        "id": "chip-gap",
        "label": "Chip gap",
        "kind": "exact",
        "token": "--cds-space-8",
        "value": 8,
        "unit": "px",
        "appliesTo": [
          "root"
        ]
      }
    ],
    "layout": {
      "alignment": "Chips share a center line and read in source order.",
      "flow": "A wrapping row by default, or one scrolling line when `scroll` is set.",
      "notes": [
        "Keep one kind of chip in a group. Mixing selectable and removable chips gives two different affordances the same shape.",
        "Use Tag for a marker that does nothing, and keep it outside the group.",
        "Use SegmentedControl instead for a fixed set of 5 or fewer mutually exclusive view modes."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Inherited",
          "description": "ChipGroup sets no type; its chips own their text. Ramp noted for parity.",
          "token": "--cds-type-body-small-size"
        }
      ],
      "colors": [
        {
          "label": "Transparent",
          "description": "ChipGroup paints no background; the surface behind shows through.",
          "token": "--cds-bg-page"
        }
      ]
    },
    "states": [
      {
        "id": "wrap",
        "label": "Wrap",
        "description": "Chips flow onto more lines."
      },
      {
        "id": "scroll",
        "label": "Scroll",
        "description": "Chips stay on one line and scroll."
      }
    ],
    "behavior": [
      {
        "label": "Selection lives with the caller",
        "description": "The group does not own selected state. Each Chip receives its own `selected` and `onPress`, so single and multiple selection both work without a second component."
      },
      {
        "label": "One kind per group",
        "description": "Do not mix selectable and removable chips in one group, and do not make only some of them interactive."
      }
    ],
    "accessibility": [
      {
        "label": "Group name",
        "description": "`label` is required and becomes the group's accessible name, so the set is announced before its chips."
      },
      {
        "label": "Focus stops",
        "description": "Each chip keeps its own focus stop. The group adds no tab stop of its own."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Growing sets",
        "description": "Prefer wrapping when the count comes from data. Reach for `scroll` only when the set is known and short."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "No group motion",
          "description": "Adding or removing a chip reflows the row without an entrance animation."
        }
      ],
      "haptics": [
        {
          "label": "Owned by the chip",
          "description": "The group requests no haptics. Each Chip fires `selection` on press."
        }
      ]
    },
    "platformDifferences": []
  },
  "platforms": {
    "implemented": [
      "web"
    ],
    "native": "Imported design guidance only; no native implementation or parity verification in this preview.",
    "react": {
      "implementation": "local",
      "status": "preview",
      "parity": "web-reference"
    },
    "vue": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "swift": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "kotlin": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    }
  },
  "tokens": [
    {
      "name": "--cds-space-8",
      "light": "8px",
      "dark": "8px"
    },
    {
      "name": "--cds-type-body-small-size",
      "light": "0.875rem",
      "dark": "0.875rem"
    },
    {
      "name": "--cds-bg-page",
      "light": "#f3f1ed",
      "dark": "#141410"
    }
  ],
  "review": {
    "local_status": "not-reviewed",
    "source_approval": null,
    "imported_spec_status": "approved",
    "spec_origin": "imported-adapted",
    "local_spec_source_status": "approved",
    "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
    "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract."
  },
  "missing_facts": [
    {
      "code": "human-review-pending",
      "detail": "This local preview has no recorded human design or engineering sign-off."
    },
    {
      "code": "platform-parity-unverified",
      "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
    },
    {
      "code": "figma-mapping-unverified",
      "detail": "No current component-level Figma node and immutable revision have been verified for this contract."
    }
  ]
}
```

## Visual states

- [Filters](/storybook/iframe.html?id=cloaked-design-system-controls-chipgroup--filters&viewMode=story) | export: Filters | source: packages/design-system/src/components/controls/ChipGroup/ChipGroup.stories.tsx

- [Removable Values](/storybook/iframe.html?id=cloaked-design-system-controls-chipgroup--removable-values&viewMode=story) | export: RemovableValues | source: packages/design-system/src/components/controls/ChipGroup/ChipGroup.stories.tsx

- [Scrolling](/storybook/iframe.html?id=cloaked-design-system-controls-chipgroup--scrolling&viewMode=story) | export: Scrolling | source: packages/design-system/src/components/controls/ChipGroup/ChipGroup.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-controls-chipgroup--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/controls/ChipGroup/ChipGroup.stories.tsx

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.