# Data Item
> Component for presenting single key-value pair.

## Import

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

DataItem is a compound component that consists of multiple parts.

- `DataItem.Root`: A container for all the parts of the data item.
- `DataItem.Label`: Contains the key of the key-value pair. The key is a field name, identifier or attribute.
- `DataItem.Value`: Contains the value of the key-value pair. The value is the data that is being identified.

## Examples

### Basic

`DataItem` is the easiest way to visually represent some data. Use it when you need to:

- visually associate a key with a value
- display data in a consistent way
- decrease the lookup time for a value

```jsx
<DataItem.Root>
  <DataItem.Label>{'Country'}</DataItem.Label>
  <DataItem.Value>{'Norway'}</DataItem.Value>
</DataItem.Root>
```

### Sizes

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

```jsx
() => {
  const formatNumber = value => value.toLocaleString('en-GB');

  return (
    <Flex flow="column" gap="spacingL">
      <Flex flow="column" gap="spacingS">
        <DataItem.Root size="small">
          <DataItem.Label>{'Capital'}</DataItem.Label>
          <DataItem.Value>{'Oslo'}</DataItem.Value>
        </DataItem.Root>
        <DataItem.Root size="small">
          <DataItem.Label>{'Population'}</DataItem.Label>
          <DataItem.Value>{formatNumber(709037)}</DataItem.Value>
        </DataItem.Root>
      </Flex>
      <Flex flow="column">
        <DataItem.Root size="medium">
          <DataItem.Label>{'Capital'}</DataItem.Label>
          <DataItem.Value>{'Oslo'}</DataItem.Value>
        </DataItem.Root>
        <DataItem.Root size="medium">
          <DataItem.Label>{'Population'}</DataItem.Label>
          <DataItem.Value>{formatNumber(709037)}</DataItem.Value>
        </DataItem.Root>
      </Flex>
    </Flex>
  );
};
```

### Emphasized

`emphasized` property makes it possible to emphasize the information according to their importance.
When emphasized the larger font size creates a stronger visual impact.

```jsx
() => {
  const formatCurrency = value =>
    value.toLocaleString('en-GB', { style: 'currency', currency: 'EUR' });

  return (
    <Flex flow="column">
      <DataItem.Root size="small" emphasized>
        <DataItem.Label>{'Weekly income'}</DataItem.Label>
        <DataItem.Value>{formatCurrency(46298)}</DataItem.Value>
      </DataItem.Root>
      <DataItem.Root size="medium" emphasized>
        <DataItem.Label>{'Monthly income'}</DataItem.Label>
        <DataItem.Value>{formatCurrency(125953)}</DataItem.Value>
      </DataItem.Root>
    </Flex>
  );
};
```

### Reversed

By default, label will display below the value. Set the `reversed` property to `true` to visually swap the positions of the label and value (label above value).

<Callout variant="tip">

Note that `DataItem.Label` still needs to come before `DataList.Value` in the markup because we're using a [description list](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl) for the underlying elements.

</Callout>

- Use label below value if you want to emphasize the value.
- Use label above value if the key has an equal importance to the value.

```jsx
<DataItem.Root size="medium" reversed>
  <DataItem.Label>{'Unique visitors'}</DataItem.Label>
  <DataItem.Value>{'142.1k'}</DataItem.Value>
</DataItem.Root>
```

### Info Tip

Combine `DataItem` with [Tooltip](/components/tooltip) to provide additional context about the value.

```jsx
() => {
  const formatNumber = value => value.toLocaleString('en-GB');

  return (
    <Flex flow="column">
      <Flex wrap="wrap">
        <DataItem.Root size="small">
          <DataItem.Label>{'Total users'}</DataItem.Label>
          <DataItem.Value>{formatNumber(10000)}</DataItem.Value>
        </DataItem.Root>
        <DataItem.Root size="small">
          <DataItem.Label>
            <Flex gap="spacingXs">
              {'Users change'}
              <Tooltip content="Users change since last month" delay={0}>
                <Button withLoneIcon size="xxSmall" variant="ghost">
                  <SvgIcon iconName="info" />
                </Button>
              </Tooltip>
            </Flex>
          </DataItem.Label>
          <DataItem.Value>{'+45'}</DataItem.Value>
        </DataItem.Root>
      </Flex>
      <Flex wrap="wrap">
        <DataItem.Root>
          <DataItem.Label>{'Total users'}</DataItem.Label>
          <DataItem.Value>{formatNumber(10000)}</DataItem.Value>
        </DataItem.Root>
        <DataItem.Root>
          <DataItem.Label>
            <Flex gap="spacingXs">
              {'Users change'}
              <Tooltip content="Users change since last month" delay={0}>
                <Button withLoneIcon size="xSmall" variant="ghost">
                  <SvgIcon iconName="info" />
                </Button>
              </Tooltip>
            </Flex>
          </DataItem.Label>
          <DataItem.Value>{'+45'}</DataItem.Value>
        </DataItem.Root>
      </Flex>
    </Flex>
  );
};
```

### Trend

Combine `DataItem` with [Label](/components/label) to display a trend indicator next to the value.

```jsx
() => {
  const formatCurrency = value =>
    value.toLocaleString('en-GB', { style: 'currency', currency: 'EUR' });

  return (
    <Flex flow="column">
      <DataItem.Root emphasized>
        <DataItem.Label>{'Total revenue'}</DataItem.Label>
        <Flex gap="spacingS">
          <DataItem.Value>{formatCurrency(10405.4)}</DataItem.Value>
          <Label
            variant="subtle"
            color="success"
            startElement={<SvgIcon iconName="arrowUp" />}
          >
            {'14%'}
          </Label>
        </Flex>
      </DataItem.Root>
      <DataItem.Root emphasized size="small">
        <DataItem.Label>{'Total revenue'}</DataItem.Label>
        <Flex gap="spacingS">
          <DataItem.Value>{formatCurrency(9156.75)}</DataItem.Value>
          <Label
            variant="subtle"
            size="small"
            color="danger"
            startElement={<SvgIcon iconName="arrowDown" />}
          >
            {'12%'}
          </Label>
        </Flex>
      </DataItem.Root>
    </Flex>
  );
};
```

### Value unit

If your value contains a unit, for example, meters, seconds, hours etc., you may wrap it in `DataItem.ValueUnit` for improved readability.

```jsx
<Flex flow="column">
  <DataItem.Root emphasized>
    <DataItem.Label>{'Time to complete'}</DataItem.Label>
    <DataItem.Value>
      <Flex gap="spacingXs" cross="baseline">
        {'2'} <DataItem.ValueUnit>{'hr'}</DataItem.ValueUnit>
        {'20'} <DataItem.ValueUnit>{'min'}</DataItem.ValueUnit>
      </Flex>
    </DataItem.Value>
  </DataItem.Root>
  <DataItem.Root emphasized>
    <DataItem.Label>{'Capacity'}</DataItem.Label>
    <DataItem.Value>
      <Flex gap="spacingXs" cross="baseline">
        {'100'} <DataItem.ValueUnit>{'MW'}</DataItem.ValueUnit>
      </Flex>
    </DataItem.Value>
  </DataItem.Root>
</Flex>
```

### Multiple items

<Callout variant="tip">

For larger amount of data items, consider using [Data
List](/components/data-list) component instead.

</Callout>

Data items can be arranged in many ways and composed with other components.

Use [Flex component](/components/layout/flex) to layout a group of data items in a row and allow them to wrap onto a new line.

```jsx
() => {
  const formatCurrency = value =>
    value.toLocaleString('en-GB', { style: 'currency', currency: 'EUR' });

  return (
    <Flex gap="spacingL" wrap="wrap">
      <DataItem.Root>
        <DataItem.Label>{'Employees'}</DataItem.Label>
        <DataItem.Value>{'847'}</DataItem.Value>
      </DataItem.Root>
      <DataItem.Root>
        <DataItem.Label>{'Years in business'}</DataItem.Label>
        <DataItem.Value>{'23'}</DataItem.Value>
      </DataItem.Root>
      <DataItem.Root>
        <DataItem.Label>{'Customers'}</DataItem.Label>
        <DataItem.Value>{'122'}</DataItem.Value>
      </DataItem.Root>
      <DataItem.Root>
        <DataItem.Label>{'Revenue'}</DataItem.Label>
        <DataItem.Value>{formatCurrency(812327.5)}</DataItem.Value>
      </DataItem.Root>
    </Flex>
  );
};
```

Or use the [Auto Grid](/components/layout/auto-grid) to layout data items in configurable, responsive columns.

```jsx
<ContentBlock max="containerNarrow" gutters="none" center={false}>
  <AutoGrid min="10ch">
    <DataItem.Root>
      <DataItem.Label>{'Country'}</DataItem.Label>
      <DataItem.Value>{'Norway'}</DataItem.Value>
    </DataItem.Root>
    <DataItem.Root>
      <DataItem.Label>{'City'}</DataItem.Label>
      <DataItem.Value>{'Oslo'}</DataItem.Value>
    </DataItem.Root>
    <DataItem.Root>
      <DataItem.Label>{'Latitude'}</DataItem.Label>
      <DataItem.Value>{'59.913'}</DataItem.Value>
    </DataItem.Root>
    <DataItem.Root>
      <DataItem.Label>{'Longitude'}</DataItem.Label>
      <DataItem.Value>{'10.746'}</DataItem.Value>
    </DataItem.Root>
  </AutoGrid>
</ContentBlock>
```

### Inside Card

Nest `DataItem` inside [Card](/components/card) to highlight some key indicators or important metrics in a dashboard-like fashion.

```jsx
<ContentBlock max="containerMedium" gutters="none" center={false}>
  <Flex flow="column">
    <Heading as="h3">{'Instances overview'}</Heading>
    <AutoGrid min="30ch">
      <Card.Root as="button" type="button" interactive>
        <Flex cross="start">
          <SvgIcon
            iconName="check"
            size="large"
            marginTop="spacingS"
            color="foregroundInfoSubtle"
          />
          <DataItem.Root emphasized>
            <DataItem.Label>{'Completed'}</DataItem.Label>
            <DataItem.Value>{'15'}</DataItem.Value>
          </DataItem.Root>
        </Flex>
      </Card.Root>
      <Card.Root as="button" type="button" interactive>
        <Flex cross="start">
          <SvgIcon
            iconName="play"
            size="large"
            marginTop="spacingS"
            color="foregroundSuccessSubtle"
          />
          <DataItem.Root emphasized>
            <DataItem.Label>{'Running'}</DataItem.Label>
            <DataItem.Value>{'28'}</DataItem.Value>
          </DataItem.Root>
        </Flex>
      </Card.Root>
      <Card.Root as="button" type="button" interactive>
        <Flex cross="start">
          <SvgIcon
            iconName="close"
            size="large"
            marginTop="spacingS"
            color="foregroundWarningSubtle"
          />
          <DataItem.Root emphasized>
            <DataItem.Label>{'Terminated'}</DataItem.Label>
            <DataItem.Value>{'17'}</DataItem.Value>
          </DataItem.Root>
        </Flex>
      </Card.Root>
    </AutoGrid>
  </Flex>
</ContentBlock>
```

```jsx
<Box css={{ maxWidth: 400 }}>
  <Card.Root>
    <Card.Header>{'Status'}</Card.Header>
    <Card.Body>
      <AutoGrid min="20ch" alignItems="start">
        <DataItem.Root emphasized>
          <DataItem.Label>{'Generators in total'}</DataItem.Label>
          <DataItem.Value>{'28'}</DataItem.Value>
        </DataItem.Root>
        <DataItem.Root emphasized>
          <DataItem.Label>{'In maintenence'}</DataItem.Label>
          <DataItem.Value color="foregroundNeutralSubtle">{'4'}</DataItem.Value>
        </DataItem.Root>
        <DataItem.Root emphasized>
          <DataItem.Label>{'Failing'}</DataItem.Label>
          <Flex gap="spacingS">
            <DataItem.Value color="foregroundDanger">{'2'}</DataItem.Value>
            <SvgIcon
              iconName="warning"
              color="foregroundDanger"
              size="medium"
            />
          </Flex>
        </DataItem.Root>
      </AutoGrid>
    </Card.Body>
  </Card.Root>
</Box>
```

---

## API Reference

### DataItem.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 item.                                                                                                                                                                                                                   |          |
| `emphasized` | `boolean`             | `false`    | Controls whether data item is emphasized.                                                                                                                                                                                                    |          |
| `reversed`   | `boolean`             | `false`    | Controls whether label and value should be reversed.                                                                                                                                                                                         |          |

### DataItem.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. |          |

### DataItem.Value

<Callout variant="tip">

In addition to the props below, you can pass [Text props](/components/typography/text#api-reference) for controlling the text appearance.

</Callout>

| 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. |          |

### DataItem.ValueUnit

| 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. |          |