---
title: Apply notes to carts
description: Use a cart handler to apply a note to a cart.
source_url:
  html: 'https://shopify.dev/docs/storefronts/headless/legacy/hydrogen/cart/notes'
  md: 'https://shopify.dev/docs/storefronts/headless/legacy/hydrogen/cart/notes.md'
api_name: hydrogen
---

Legacy Hydrogen

These pages refer to Hydrogen versions 2026-04 and earlier. For versions 2026-10 and later, refer to the latest [Hydrogen docs](https://shopify.dev/docs/storefronts/hydrogen). If you're not using the latest version of Hydrogen, then we recommend that you migrate your storefront. To learn more, refer to [Migrate to the latest version of Hydrogen](https://shopify.dev/docs/storefronts/hydrogen/migrate).

# Apply notes to carts

This guide shows you how to use a cart handler to apply a note to a cart. For example, you can enable users to apply a note that requests gift-wrapping.

***

## Requirements

* You've completed the [quickstart guide](https://shopify.dev/docs/storefronts/headless/legacy/hydrogen/getting-started).
* You've [set up a cart handler](https://shopify.dev/docs/storefronts/headless/legacy/hydrogen/cart/setup).

***

## Step 1: Create a cart note form

Use the [`CartForm`](https://shopify.dev/docs/api/hydrogen/2026-04/components/cartform) component to create a cart note form. The component submits a form request to the `/cart` route's action when users submit an update to the note. You can use this component anywhere in the app.

## File

## /app/components/NoteForm.jsx

##### JavaScript

```jsx
import {CartForm} from '@shopify/hydrogen';

export default function NoteForm() {
  return (
    <CartForm
      route="/cart"
      action={CartForm.ACTIONS.NoteUpdate}
    >
      <p>Provide a short message for the gift tag:</p>
      <input type="text" name="note" />
      <button>Update note</button>
    </CartForm>
  );
}
```

##### TypeScript

```jsx
import {CartForm} from '@shopify/hydrogen';

export default function NoteForm() {
  return (
    <CartForm
      route="/cart"
      action={CartForm.ACTIONS.NoteUpdate}
    >
      <p>Provide a short message for the gift tag:</p>
      <input type="text" name="note" />
      <button>Update note</button>
    </CartForm>
  );
}
```

***

## Step 2: Handle the cart note form request

Handle the cart note form request in an `action`. Use the `cart`, created from [`createCartHandler`](https://shopify.dev/docs/api/hydrogen/2026-04/utilities/cart/createcarthandler), to handle cart mutation requests to the Storefront API.

## File

## /app/routes/cart.jsx

##### JavaScript

```jsx
import {CartForm} from '@shopify/hydrogen';
import invariant from 'tiny-invariant';

export async function action({request, context}) {
  const {cart} = context;

  const formData = await request.formData();
  const {action, inputs} = CartForm.getFormInput(formData);

  let result;

  switch(action) {
    case CartForm.ACTIONS.NoteUpdate:
      const note = String(formData.get('note') || '');
      result = await cart.updateNote(note);
      break;
    default:
      invariant(false, `${action} cart action is not defined`);
  }

  // The Cart ID might change after each mutation, so update it each time.
  const headers = cart.setCartId(result.cart.id);

  return json(
    result,
    {status: 200, headers},
  );
}
```

##### TypeScript

```jsx
import {
  type CartQueryData,
  CartForm,
} from '@shopify/hydrogen';
import invariant from 'tiny-invariant';

export async function action({request, context}: ActionArgs) {
  const {cart} = context;

  const formData = await request.formData();
  const {action, inputs} = CartForm.getFormInput(formData);

  let result: CartQueryData;

  switch(action) {
    case CartForm.ACTIONS.NoteUpdate:
      const note = String(formData.get('note') || '');
      result = await cart.updateNote(note);
      break;
    default:
      invariant(false, `${action} cart action is not defined`);
  }

  // The Cart ID might change after each mutation, so update it each time.
  const headers = cart.setCartId(result.cart.id);

  return json(
    result,
    {status: 200, headers},
  );
}
```

***

## Next steps

* Learn how to [apply cart attributes](https://shopify.dev/docs/storefronts/headless/legacy/hydrogen/cart/attributes).

***