# Data List
> Component for organizing and displaying data as a list of key-value pairs.

## Import

```js
import { DataList } from '@gemini-suite/vera-react';
```

Data List is a compound component that consists of multiple parts.

- `DataList.Root`: A container for all the parts of the data list.
- `DataList.Row`: Row that wraps a key-value pair.
- `DataList.Label`: Contains the key of the key-value pair.
- `DataList.Value`: Contains the value of the key-value pair.

## Examples

### Basic

```jsx
<DataList.Root>
  <DataList.Row>
    <DataList.Label>Status</DataList.Label>
    <DataList.Value>
      <Label variant="subtle" color="success">
        Active
      </Label>
    </DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Name</DataList.Label>
    <DataList.Value>Ulf Sindre</DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Occupation</DataList.Label>
    <DataList.Value>CEO</DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Email</DataList.Label>
    <DataList.Value>
      <Link href="mailto:ulf@invera-tech.com">ulf@invera-tech.com</Link>
    </DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Phone</DataList.Label>
    <DataList.Value>+47 22222424</DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Company</DataList.Label>
    <DataList.Value>
      <Link href="https://geminisuite.com" isExternal>
        Gemini Suite
      </Link>
    </DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Bio</DataList.Label>
    <DataList.Value>
      Fusce vitae dolor a nulla rhoncus vulputate sed nec mauris. Mauris
      condimentum pretium arcu sed molestie. Suspendisse posuere vitae sapien
      sit amet tristique. Praesent non est augue. In hac habitasse platea
      dictumst. Curabitur quis diam ante. Ut at vestibulum leo. Integer porta
      posuere tincidunt. Mauris at eleifend.
    </DataList.Value>
  </DataList.Row>
</DataList.Root>
```

### Sizes

`DataList` comes in two sizes: `medium` and `small`. By default, it uses `medium` size.

```jsx
<Flex flow="column">
  <Card.Root css={{ maxWidth: 400 }}>
    <DataList.Root
      size="medium"
      orientation={{ '@initial': 'vertical', '@mqLargeAndUp': 'horizontal' }}
    >
      <DataList.Row>
        <DataList.Label>Status</DataList.Label>
        <DataList.Value>
          <Label variant="subtle" color="success">
            Active
          </Label>
        </DataList.Value>
      </DataList.Row>
      <DataList.Row>
        <DataList.Label>Plan ID</DataList.Label>
        <DataList.Value>
          <Flex gap="spacingXs">
            <Text fontFamily="mono" fontSize="zeta">
              Yg_RrUkKAz5WlLd6Y9Q1v
            </Text>
            <Tooltip delay={300} content="Copy">
              <Button withLoneIcon size="xSmall" variant="ghost">
                <SvgIcon iconName="copy" />
              </Button>
            </Tooltip>
          </Flex>
        </DataList.Value>
      </DataList.Row>
      <DataList.Row>
        <DataList.Label>Created by</DataList.Label>
        <DataList.Value>Ola Halvorsen</DataList.Value>
      </DataList.Row>
      <DataList.Row>
        <DataList.Label>Date created</DataList.Label>
        <DataList.Value>06.09.2023</DataList.Value>
      </DataList.Row>
      <DataList.Row>
        <DataList.Label>Last edited</DataList.Label>
        <DataList.Value>10.09.2023</DataList.Value>
      </DataList.Row>
    </DataList.Root>
  </Card.Root>
  <Card.Root size="small" css={{ maxWidth: 300 }}>
    <DataList.Root
      size="small"
      orientation={{ '@initial': 'vertical', '@mqLargeAndUp': 'horizontal' }}
    >
      <DataList.Row>
        <DataList.Label>Status</DataList.Label>
        <DataList.Value>
          <Label variant="subtle" color="success" size="small">
            Active
          </Label>
        </DataList.Value>
      </DataList.Row>
      <DataList.Row>
        <DataList.Label>Plan ID</DataList.Label>
        <DataList.Value>
          <Flex gap="spacingXs">
            <Text fontFamily="mono" fontSize="eta">
              Yg_RrUkKAz5WlLd6Y9Q1v
            </Text>
            <Tooltip delay={300} content="Copy">
              <Button withLoneIcon size="xxSmall" variant="ghost">
                <SvgIcon iconName="copy" />
              </Button>
            </Tooltip>
          </Flex>
        </DataList.Value>
      </DataList.Row>
      <DataList.Row>
        <DataList.Label>Created by</DataList.Label>
        <DataList.Value>Ola Halvorsen</DataList.Value>
      </DataList.Row>
      <DataList.Row>
        <DataList.Label>Date created</DataList.Label>
        <DataList.Value>06.09.2023</DataList.Value>
      </DataList.Row>
      <DataList.Row>
        <DataList.Label>Last edited</DataList.Label>
        <DataList.Value>10.09.2023</DataList.Value>
      </DataList.Row>
    </DataList.Root>
  </Card.Root>
</Flex>
```

### Orientation

Use the `orientation` prop to change the way the data list is laid out. `DataList` supports horizontal (default) and vertical orientations.

```jsx
<DataList.Root orientation="vertical">
  <DataList.Row>
    <DataList.Label>Name</DataList.Label>
    <DataList.Value>Ulf Sindre</DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Email</DataList.Label>
    <DataList.Value>
      <Link href="mailto:ulf@invera-tech.com">ulf@invera-tech.com</Link>
    </DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Company</DataList.Label>
    <DataList.Value>
      <Link href="https://geminisuite.com" isExternal>
        Gemini Suite
      </Link>
    </DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Bio</DataList.Label>
    <DataList.Value>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    </DataList.Value>
  </DataList.Row>
</DataList.Root>
```

<Callout variant="tip">

`Orientation` prop is responsive, meaning it accepts either a single orientation or an object that maps orientation to a [breakpoint](/tokens/breakpoints).

</Callout>

```jsx
<DataList.Root
  orientation={{ '@initial': 'vertical', '@mqLargeAndUp': 'horizontal' }}
>
  <DataList.Row>
    <DataList.Label>Name</DataList.Label>
    <DataList.Value>Ulf Sindre</DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Email</DataList.Label>
    <DataList.Value>
      <Link href="mailto:ulf@invera-tech.com">ulf@invera-tech.com</Link>
    </DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Company</DataList.Label>
    <DataList.Value>
      <Link href="https://geminisuite.com" isExternal>
        Gemini Suite
      </Link>
    </DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Bio</DataList.Label>
    <DataList.Value>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    </DataList.Value>
  </DataList.Row>
</DataList.Root>
```

### Row separation

Use the `rowSeparation` prop to control the appearance of row separation.

#### Stripes

```jsx
<DataList.Root rowSeparation="stripes">
  <DataList.Row>
    <DataList.Label>Name</DataList.Label>
    <DataList.Value>Ulf Sindre</DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Email</DataList.Label>
    <DataList.Value>
      <Link href="mailto:ulf@invera-tech.com">ulf@invera-tech.com</Link>
    </DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Company</DataList.Label>
    <DataList.Value>
      <Link href="https://geminisuite.com" isExternal>
        Gemini Suite
      </Link>
    </DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Bio</DataList.Label>
    <DataList.Value>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    </DataList.Value>
  </DataList.Row>
</DataList.Root>
```

#### Dividers

```jsx
<DataList.Root rowSeparation="dividers">
  <DataList.Row>
    <DataList.Label>Name</DataList.Label>
    <DataList.Value>Ulf Sindre</DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Email</DataList.Label>
    <DataList.Value>
      <Link href="mailto:ulf@invera-tech.com">ulf@invera-tech.com</Link>
    </DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Company</DataList.Label>
    <DataList.Value>
      <Link href="https://geminisuite.com" isExternal>
        Gemini Suite
      </Link>
    </DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Bio</DataList.Label>
    <DataList.Value>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    </DataList.Value>
  </DataList.Row>
</DataList.Root>
```

### Customize column sizes

By default the label column in horizontal orientation extends to accommodate the label and the value column fills the rest of available space.
Use the `columnSizes` property, to control the size of the label and value columns in horizontal orientation.

```jsx
<DataList.Root
  orientation={{ '@initial': 'vertical', '@mqLargeAndUp': 'horizontal' }}
  columnSizes={['1fr', '3fr']}
>
  <DataList.Row>
    <DataList.Label>Term</DataList.Label>
    <DataList.Value>Details</DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Owner</DataList.Label>
    <DataList.Value>John Doe</DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Phone</DataList.Label>
    <DataList.Value>+47 22222424</DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Long label that wraps to a next line</DataList.Label>
    <DataList.Value>
      Fusce vitae dolor a nulla rhoncus vulputate sed nec mauris.
    </DataList.Value>
  </DataList.Row>
</DataList.Root>
```

### Align value to end

Use `alignValueToEnd` property to align the value to an end of the column in horizontal orientation, useful for numeric or similar data.

<Callout variant="tip">

Sometimes it makes sense to emphasise the label instead of the data (i.e. if it helps the user to scan more easily for the right information).

Set `emphasize` property to `label` to give labels more emphasis.

</Callout>

```jsx
<DataList.Root rowSeparation="dividers" emphasize="label" alignValueToEnd>
  <DataList.Row>
    <DataList.Label>Elevation</DataList.Label>
    <DataList.Value>1543 m.</DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Humidity</DataList.Label>
    <DataList.Value>46%</DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Temperature</DataList.Label>
    <DataList.Value>8 °C</DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Wind</DataList.Label>
    <DataList.Value>NE 16 km/h</DataList.Value>
  </DataList.Row>
  <DataList.Row>
    <DataList.Label>Pressure</DataList.Label>
    <DataList.Value>1021 mb</DataList.Value>
  </DataList.Row>
</DataList.Root>
```

---

## API Reference

### DataList.Root

| Name              | Type                         | Default        | Description                                                                                                                                                                                                                                  | Required |
| ----------------- | ---------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css`             | `StitchesCss`                |                | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants. |          |
| `size`            | `"medium" \| "small"`        | `"medium"`     | The size of the data list.                                                                                                                                                                                                                   |          |
| `orientation`     | `"horizontal" \| "vertical"` | `"horizontal"` | Defines orientation of the data list. Supports responsive syntax.                                                                                                                                                                            |          |
| `columnSizes`     | `[string, string]`           |                | Defines the relative or absolute width of each column in horizontal orientation. By default `DataList.Label` extends to accommodate the content and `DataList.Value` fills the rest of available space.                                      |          |
| `rowSeparation`   | `"dividers" \| "stripes"`    |                | Defines the appearance of row separation to aid users to distinguish rows.                                                                                                                                                                   |          |
| `alignValueToEnd` | `boolean`                    | `false`        | When `true`, `DataList.Value` is aligned to an end of the column in horizontal orientation.                                                                                                                                                  |          |
| `emphasize`       | `"value" \| "label"`         | `"value"`      | Controls whether value or label should have emphasis.                                                                                                                                                                                        |          |

### DataList.Row

| Name         | Type                                                    | Default | Description                                                                                                                                                                                                                                  | Required |
| ------------ | ------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css`        | `StitchesCss`                                           |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants. |          |
| `alignItems` | `"start" \| "center" \| "end" \| "baseline", "stretch"` |         | Defines the alignment of the items on the block (column) axis.                                                                                                                                                                               |          |

### DataList.Label

| Name  | Type          | Default | Description                                                                                                                                                                                                                                  | Required |
| ----- | ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css` | `StitchesCss` |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants. |          |

### DataList.Value

| Name  | Type          | Default | Description                                                                                                                                                                                                                                  | Required |
| ----- | ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css` | `StitchesCss` |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants. |          |