Quantity `<mv-quantity>`

E-commerce quantity picker, a thin variant of <mv-number-field>: minimum 1, automatically capped at stock, an “In stock” / “Only 3 left in stock” / “Out of stock” caption linked to the field, a message and shake when hitting the stock limit, a disabled sold-out state that re-enables on restock; pill and subtle variants for cart lines.

Category	Forms
Type	Web Component (`<mv-quantity>`)
Status	stable
Also installs	number-field
Keywords	quantity, quantité, stepper, stock, out-of-stock, cart, e-commerce, form-associated

When to use

A product page or cart line needs a quantity picker capped at available stock
Shoppers should see In stock, Only 3 left or Out of stock next to the quantity
A compact pill or muted variant must fit inside cart rows

Avoid when

The number is not a purchase quantity, like a price, percentage or measurement → use Number Field instead
The whole purchase block with variants, price and add to cart is needed → use Buy Box instead

Install

node scripts/add.mjs quantity --out ./src/marvelous

AI agent with the Marvelous UI MCP server: install_components({ slugs: ["quantity"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).

Files copied (dependencies included): tokens/tokens.css, core/base.css, core/dom.js, core/element.js, core/i18n.js, core/motion.js, components/number-field/number-field.js, components/number-field/number-field.css, components/quantity/quantity.js, components/quantity/quantity.css.

Usage

Canonical markup, to start from and customize with attributes, data-* and CSS variables:

<div id="quantity-demo" style="display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,14rem),1fr));gap:1.25rem;width:min(100%,50rem);margin-inline:auto;font-size:.875rem">
  <style>
    #quantity-demo .panel { display:grid; gap:.875rem; align-content:start; padding:1.25rem; border:1px solid var(--mv-border); border-radius:var(--mv-radius-xl); background:var(--mv-surface) }
    #quantity-demo .cap { margin:0; font-size:.75rem; font-weight:500; color:var(--mv-fg-muted) }
  </style>

  <form class="panel" id="quantity-demo-form" onsubmit="event.preventDefault()">
    <p class="cap">In stock</p>
    <mv-quantity label="Quantity" name="quantity" value="1" stock="24"></mv-quantity>
  </form>

  <div class="panel">
    <p class="cap">Low stock · capped</p>
    <mv-quantity label="Quantity" name="quantity-2" value="2" stock="3" data-variant="pill"></mv-quantity>
  </div>

  <div class="panel">
    <p class="cap">Out of stock</p>
    <mv-quantity label="Quantity" name="quantity-3" value="1" stock="0"></mv-quantity>
    <button class="mv-button" data-variant="outline" data-size="sm" id="quantity-demo-restock" style="justify-self:start">Restock (+12)</button>
  </div>

  <div class="panel">
    <p class="cap">Cart line (compact)</p>
    <div style="display:flex;align-items:center;justify-content:space-between;gap:.75rem">
      <span style="font-weight:500">Stoneware mug</span>
      <mv-quantity value="2" max="10" data-size="sm" data-variant="ghost" caption="none" aria-label="Quantity, Stoneware mug"></mv-quantity>
    </div>
    <div style="display:flex;align-items:center;justify-content:space-between;gap:.75rem">
      <span style="font-weight:500">Fig candle</span>
      <mv-quantity value="1" max="10" data-size="sm" data-variant="ghost" caption="none" aria-label="Quantity, Fig candle"></mv-quantity>
    </div>
  </div>
</div>
<script type="module">
  const root = document.getElementById("quantity-demo");
  root.querySelector("#quantity-demo-restock").addEventListener("click", (e) => {
    const q = root.querySelector('mv-quantity[name="quantity-3"]');
    q.stock = (q.stock ?? 0) + 12;
    e.currentTarget.disabled = true;
  });
</script>

API

Attributes

Name	Type	Default	Description
`value / name / label`	number / string		Same as `<mv-number-field>` (submits an integer value).
`min`	number	`1`	Minimum quantity.
`max`	number		Commercial cap (e.g. 10 per order); combined with stock, the smaller one wins.
`stock`	number		Available stock: caps the value and drives the caption; 0 = out of stock (disabled).
`low-stock`	number	`5`	Threshold for the “Only n left in stock” caption.
`caption`	auto \| none \| text	`auto`	Automatic caption, none, or free text.
`data-size`	sm \| md		Height (lg by default, sized to match an “Add to cart” button).
`data-variant`	pill \| ghost		Rounded pill, or muted background without a border.
`disabled / readonly / required`	boolean		Form states.

Properties

Name	Type	Description
`value`	number \| null	Quantity.
`stock`	number	Stock (assignable: restock).
`inStock`	boolean	Read-only.
`strings`	Partial<Record<string, string \| { one, other }>>	Overrides for the default text (en-US): quantity (default accessible name), inStock, outOfStock, lastOne (stock of 1), onlyLeft (low stock, {n}, { one, other }), maxAvailable (shown at the stock limit, {n}, { one, other }), plus the number-field keys decrease, increase and valueMissing. App-wide translations: setStrings() from core/i18n.js, under the key "quantity". Can be set before the element is defined.

Methods

Name	Description
`stepUp(n) / stepDown(n) / focus()`	Inherited from `<mv-number-field>`.

Events

Name	Description
`mv-change`	detail: { value, formatted } (inherited).

CSS classes

Name	Description
`mv-quantity-caption`	Stock caption; data-tone = success \| warning \| danger.
`data-stock`	On the host: none \| in \| low \| out.

CSS variables

Name	Default	Description
`--mv-quantity-width`	`8.25rem`	Width.

Accessibility

Inherits the APG Spinbutton pattern from <mv-number-field> (arrows, Page↑/↓, Home/End, “Decrease” / “Increase” buttons outside the tab order). Default name “Quantity”. The stock caption is linked via aria-describedby; the “Maximum quantity” message is announced (aria-live polite) when trying to exceed the stock. When out of stock, the field is disabled and empty (dash).