# Cart Totals

> CartTotalsList and total atoms for cart and order summary totals.

# Cart Totals

Use `OmeWooCartAmount` for new cart total interfaces. It renders one explicitly selected shopper-facing amount, follows WooCommerce tax display rules by default, and distinguishes a calculated zero from a value that WooCommerce has not calculated yet.

## Quick Start

Place one Cart Amount component in `OmeWooCartTotalsList` for each row you want to show. An empty `content.label` uses the automatic label for the selected measure and current state.

<CodeExample title="Tax-aware cart total rows" language="jsx">
	{`<OmeWooCartTotalsList>
  <OmeWooCartAmount
    amount='{{"measure":"items_subtotal","tax_presentation":"store"}}'
    content='{{"show_label":true,"label":"","label_position":"prefix"}}'
  />
  <OmeWooCartAmount
    amount='{{"measure":"shipping","tax_presentation":"store","pending_text":"Not calculated"}}'
    content='{{"show_label":true,"label":"","label_position":"prefix"}}'
  />
  <OmeWooCartAmount
    amount='{{"measure":"tax"}}'
    content='{{"show_label":true,"label":""}}'
  />
  <OmeWooCartAmount
    amount='{{"measure":"final_total"}}'
    content='{{"show_label":true,"label":""}}'
  />
</OmeWooCartTotalsList>`}
</CodeExample>

`final_total` is the default measure, so a bare `<OmeWooCartAmount />` is a valid compact final-total readout.

## Shopper Measures

`amount.measure` offers exactly six measures:

| Measure          | What the shopper sees                                                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `items_subtotal` | Product subtotal before discounts, fees, and shipping.                                                                                        |
| `discount`       | Discount magnitude rendered as a negative amount. Non-zero discounts always have a minus sign; formatted zero stays unsigned.                 |
| `fees`           | Cart fees.                                                                                                                                    |
| `shipping`       | Calculated shipping, or the pending text while required shipping is unresolved.                                                               |
| `tax`            | WooCommerce's direct tax total. Its automatic label is `Included tax` when the store displays cart prices including tax, and `Tax` otherwise. |
| `final_total`    | WooCommerce's direct final total. Its automatic label becomes `Estimated total` while required shipping is unresolved.                        |

The first four measures are net/tax pairs. For those measures only, `amount.tax_presentation` controls whether the displayed amount includes tax:

| Value           | Behavior                                                                       |
| --------------- | ------------------------------------------------------------------------------ |
| `store`         | Follows the store's WooCommerce cart tax-display setting. This is the default. |
| `including_tax` | Adds the matching direct tax field to the measure's direct net field.          |
| `excluding_tax` | Uses the measure's direct net field.                                           |

`tax` and `final_total` do not expose this choice. Cart Amount uses `total_tax` and `total_price` directly and never reconstructs either value. In particular, Store API `total_price` already contains any applicable tax; adding `total_tax` again would overstate the shopper's total.

## Shipping And Public States

A resolved shipping amount of zero is free shipping and renders as the correctly formatted currency zero, such as `$0.00`. When the cart needs shipping but WooCommerce has not calculated it, the canonical shipping value remains `null`: the shipping measure renders `amount.pending_text` (default `Not calculated`) and exposes `data-ome-state="pending"`.

The final total still renders WooCommerce's direct `total_price` while shipping is unresolved, but exposes `data-ome-state="estimated"` and uses the automatic label `Estimated total`. It does not guess a shipping cost.

The public states are exactly:

| State       | Meaning                                                                         |
| ----------- | ------------------------------------------------------------------------------- |
| `resolved`  | The selected measure is available, including a genuine zero.                    |
| `pending`   | Required shipping has not been calculated; used by the shipping measure.        |
| `estimated` | The direct final total is available, but required shipping is still unresolved. |

An empty cart resolves its available measures as a correctly formatted currency zero rather than an empty string.

Server-rendered text remains in place until the Cart Store has a confirmed hydrated snapshot. Cart Amount does not optimistically rewrite totals, mutate the cart, emit custom events, or create an `aria-live` region.

## Props

### Content

| Prop                     | Default  | Meaning                                                                                                               |
| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `content.show_label`     | `false`  | Shows a visible label and value row. When false, a visually hidden label still provides the amount's accessible name. |
| `content.label`          | empty    | Empty uses the automatic measure/state label. A non-empty authored value overrides that label.                        |
| `content.label_position` | `prefix` | Places the visible label before (`prefix`) or after (`suffix`) the value. Available when `show_label` is true.        |

With `show_label=false`, the hidden accessible text combines the active label and value, for example `Shipping: Not calculated`. The visible value is hidden from assistive technology to avoid duplicate announcements. A non-empty authored label is still respected in this mode.

### Amount

| Prop                      | Default          | Meaning                                                                                                          |
| ------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `amount.measure`          | `final_total`    | Selects `items_subtotal`, `discount`, `fees`, `shipping`, `tax`, or `final_total`.                               |
| `amount.tax_presentation` | `store`          | Selects `store`, `including_tax`, or `excluding_tax`. Available only for subtotal, discount, fees, and shipping. |
| `amount.pending_text`     | `Not calculated` | Copy shown for unresolved shipping. Available only when `measure=shipping`.                                      |

### Structure And Styling

| Prop                  | Meaning                                                |
| --------------------- | ------------------------------------------------------ |
| `structure.html_tag`  | Wrapper tag used when `content.show_label` is true.    |
| `styling.value_class` | Class prop for the amount value.                       |
| `styling.class`       | Wrapper class when the visible label is enabled.       |
| `styling.label_class` | Visible label class when the visible label is enabled. |

`OmeWooCartTotalsList` keeps its existing `structure.root_tag` wrapper prop and `styling.list_class` class prop.

## DOM And CSS Contract

The amount root exposes:

- `data-ome-woo-cart-amount`
- `data-ome-woo-cart-amount-measure`
- `data-ome-woo-tax-presentation`
- `data-ome-state` with `resolved`, `pending`, or `estimated`

The value exposes `data-ome-woo-cart-amount-value`; the visible or visually hidden label exposes `data-ome-woo-cart-amount-label`.

Stable classes include `ome-woo-cart-amount` on the root, `ome-woo-cart-amount__value` on the value, and `ome-woo-cart-amount__label` on a visible label. Labeled rows also retain the shared `ome-woo-cart-total`, `ome-woo-cart-totals__row`, `ome-woo-cart-totals__label`, and `ome-woo-cart-totals__value` classes.

```css
[data-ome-woo-cart-amount-measure="discount"]
  [data-ome-woo-cart-amount-value] {
  color: var(--accent);
}

[data-ome-woo-cart-amount-measure="final_total"][data-ome-state="estimated"] {
  opacity: 0.75;
}

[data-ome-woo-cart-amount-measure="shipping"][data-ome-state="pending"]
  .ome-woo-cart-amount__value {
  font-style: italic;
}
```

## Canonical Dynamic Data

`cartTotals.cartAmount` is the additive canonical lane used for Cart Amount's server-rendered values. Monetary values use Store API minor units and keep split net/tax fields rather than pre-combining them:

| Expression                                                                              | Meaning                                                                                    |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `{cartTotals.cartAmount.total_items}` / `{cartTotals.cartAmount.total_items_tax}`       | Items subtotal net and matching tax.                                                       |
| `{cartTotals.cartAmount.total_discount}` / `{cartTotals.cartAmount.total_discount_tax}` | Discount net and matching tax.                                                             |
| `{cartTotals.cartAmount.total_fees}` / `{cartTotals.cartAmount.total_fees_tax}`         | Fees net and matching tax.                                                                 |
| `{cartTotals.cartAmount.total_shipping}` / `{cartTotals.cartAmount.total_shipping_tax}` | Shipping net and matching tax; both remain nullable while required shipping is unresolved. |
| `{cartTotals.cartAmount.total_tax}`                                                     | Direct tax total.                                                                          |
| `{cartTotals.cartAmount.total_price}`                                                   | Direct final total, already including applicable tax.                                      |
| `{cartTotals.cartAmount.needs_shipping}`                                                | Whether the cart requires shipping.                                                        |
| `{cartTotals.cartAmount.has_calculated_shipping}`                                       | Whether WooCommerce has calculated shipping.                                               |
| `{cartTotals.cartAmount.tax_display}`                                                   | Normalized `including_tax` or `excluding_tax` store presentation.                          |
| `{cartTotals.cartAmount.currency_*}`                                                    | Store API-compatible currency code, symbol, minor unit, separators, prefix, and suffix.    |

Use the component rather than binding these fields manually when you want tax-presentation logic, discount signs, pending states, automatic labels, and confirmed Cart Store hydration.

## Released Legacy Total Atoms

`OmeWooTotalsSubtotal`, `OmeWooTotalsDiscount`, `OmeWooTotalsShipping`, `OmeWooTotalsTax`, and `OmeWooTotalsTotal` are released legacy atoms. They remain registered and behave exactly as before for saved components and existing integrations.

| Legacy component       | Flat field                  |
| ---------------------- | --------------------------- |
| `OmeWooTotalsSubtotal` | `cartTotals.total_items`    |
| `OmeWooTotalsDiscount` | `cartTotals.total_discount` |
| `OmeWooTotalsShipping` | `cartTotals.total_shipping` |
| `OmeWooTotalsTax`      | `cartTotals.total_tax`      |
| `OmeWooTotalsTotal`    | `cartTotals.total_price`    |

Those flat raw fields, a positive discount value, and missing-value-to-zero behavior are compatibility semantics. Depending on store tax settings, they may not describe the shopper-facing tax presentation you intend. Existing atoms are not silently migrated or reinterpreted. Keep them when preserving an existing design; choose `OmeWooCartAmount` for new work.

The same released legacy atoms remain usable in `OmeWooOrderSummaryTotalsList` on checkout pages. Cart Amount is currently documented for cart-page readouts.

## Related Guides

- [Cart Page](/woo/flows/cart-page)
- [Woo Dynamic Data Tree](/woo/woo-dynamic-data-tree)
- [Order Summary](/woo/component-families/order-summary)