# ResponsiveSwitcher

The ResponsiveSwitcher component is a layout component that automatically
switches between horizontal and vertical arrangements based on the available
space. It's designed to create responsive layouts that adapt to different screen
sizes without requiring media queries.

## When to use

Use ResponsiveSwitcher when you need to:

* Create layouts that switch between horizontal and vertical arrangements based
  on container width
* Build responsive interfaces without writing media queries
* Implement flexible grid-like layouts that adapt to available space
* Create responsive form layouts
* Build adaptive content sections that work across different screen sizes

## Examples

### Basic Usage

```tsx
import React from "react";
import { ResponsiveSwitcher } from "@jobber/components/ResponsiveSwitcher";
import { Card } from "@jobber/components/Card";
import { Heading } from "@jobber/components/Heading";
import { Text } from "@jobber/components/Text";
import { Stack } from "@jobber/components/Stack";
import { Box } from "@jobber/components/Box";

export function ResponsiveSwitcherBasicExample() {
  return (
    <Stack>
      <ResponsiveSwitcher gap="base" limit={2} threshold="60ch">
        <Card>
          <Box padding="base">
            <Stack>
              <Heading level={3}>Left/Top Content</Heading>
              <Text>
                This content will switch between horizontal and vertical layout
                based on the threshold.
              </Text>
            </Stack>
          </Box>
        </Card>
        <Card>
          <Box padding="base">
            <Stack>
              <Heading level={3}>Right/Bottom Content</Heading>
              <Text>
                The layout switches when the container width is less than the
                threshold.
              </Text>
            </Stack>
          </Box>
        </Card>
      </ResponsiveSwitcher>
    </Stack>
  );
}
```

### Custom Spacing

```tsx
import React from "react";
import { ResponsiveSwitcher } from "@jobber/components/ResponsiveSwitcher";
import { Card } from "@jobber/components/Card";
import { Heading } from "@jobber/components/Heading";
import { Text } from "@jobber/components/Text";
import { Stack } from "@jobber/components/Stack";
import { Box } from "@jobber/components/Box";

export function ResponsiveSwitcherCustomSpacingExample() {
  return (
    <Stack>
      <ResponsiveSwitcher gap="12px" limit={2} threshold="40ch">
        <Card>
          <Box padding="base">
            <Stack>
              <Heading level={3}>Custom Space</Heading>
              <Text>Using a custom spacing value</Text>
            </Stack>
          </Box>
        </Card>
        <Card>
          <Box padding="base">
            <Stack>
              <Heading level={3}>Between Items</Heading>
              <Text>The gap between items is customizable</Text>
            </Stack>
          </Box>
        </Card>
      </ResponsiveSwitcher>
    </Stack>
  );
}
```

### Custom Threshold

```tsx
import React from "react";
import { ResponsiveSwitcher } from "@jobber/components/ResponsiveSwitcher";
import { Card } from "@jobber/components/Card";
import { Text } from "@jobber/components/Text";
import { Box } from "@jobber/components/Box";
import { ContentBlock } from "@jobber/components/ContentBlock";

export function ResponsiveSwitcherCustomThresholdExample() {
  return (
    <ContentBlock maxWidth="100%">
      <ResponsiveSwitcher threshold="200px">
        <Box>
          <Card>
            <Box padding="base">
              <Text>Custom breakpoint</Text>
            </Box>
          </Card>
        </Box>
        <Box>
          <Card>
            <Box padding="base">
              <Text>at 200px</Text>
            </Box>
          </Card>
        </Box>
      </ResponsiveSwitcher>
    </ContentBlock>
  );
}
```

### With Item Limit

```tsx
import React from "react";
import { ResponsiveSwitcher } from "@jobber/components/ResponsiveSwitcher";
import { Card } from "@jobber/components/Card";
import { Text } from "@jobber/components/Text";
import { Box } from "@jobber/components/Box";
import { ContentBlock } from "@jobber/components/ContentBlock";

export function ResponsiveSwitcherWithItemLimitExample() {
  return (
    <ContentBlock maxWidth="100%">
      <ResponsiveSwitcher threshold="30ch" limit={3}>
        <Card>
          <Box padding="base">
            <Text>First item</Text>
          </Box>
        </Card>
        <Card>
          <Box padding="base">
            <Text>Second item</Text>
          </Box>
        </Card>
        <Card>
          <Box padding="base">
            <Text>Third item</Text>
          </Box>
        </Card>
        <Card>
          <Box padding="base">
            <Text>Fourth item (will force all to wrap)</Text>
          </Box>
        </Card>
      </ResponsiveSwitcher>
    </ContentBlock>
  );
}
```

## Implementation Details

The ResponsiveSwitcher uses CSS Flexbox with the `flex-wrap` property to create
responsive layouts. It calculates when to switch between layouts using CSS
`calc()` and custom properties, avoiding the need for media queries.

## Related Components

* For vertical layouts with consistent spacing, use [Stack](../Stack/Stack.md)
* For horizontal layouts with wrapping, use [Cluster](../Cluster/Cluster.md)


## Props

### Web

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `threshold` | `string` | Yes | — | The minimum width of the top-level children. If this can't be met, the children will break to row. |
| `ariaAttributes` | `AriaAttributes` | No | — | Standard HTML aria attributes. Accepts all standard HTML aria attributes. |
| `as` | `CommonAllowedElements` | No | `div` | The HTML tag to render the container as. Defaults to `div`. |
| `dataAttributes` | `{ [key: `data-${string}`]: string; }` | No | — | Standard HTML data attributes. Accepts anything in a {{"data-key":"value"}} format. |
| `gap` | `GapSpacing` | No | `spaceTokens.base` | The amount of space between the children. Semantic tokens are available. |
| `id` | `string` | No | — | Standard HTML id attribute. |
| `limit` | `number` | No | `2` | Useful for dynamic content. If the number of children is greater than this, the children will break to row. |
| `role` | `AriaRole` | No | — | Standard HTML role attribute. |
| `UNSAFE_className` | `{ container?: string; }` | No | — | **Use at your own risk:** Custom class names for specific elements. This should only be used as a **last resort**. Us... |
| `UNSAFE_style` | `{ container?: CSSProperties; }` | No | — | **Use at your own risk:** Custom style for specific elements. This should only be used as a **last resort**. Using th... |