# Post Listing Wizard

> A React post listing wizard for marketplaces: category, details, photos, price, place, contact and a preview, with an autosaved draft.

- Type: React block (Blocks)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.1
- Install: `npx wingo-ui@latest add post-listing-wizard`
- Docs: https://wingo-ui.com/components/post-listing-wizard

## Interaction

Pick the category from icon tiles (drill down, Back, or type to search and press Enter for the first match); a fresh pick shows the path as a chip with Change and moves on by itself, and a title typed before offers Looks like it belongs in Bicycles. Continue (or Enter in a field, Cmd/Ctrl+Enter in the description) checks the step: errors appear under the fields, the stepper marks the step with !, the button shakes and focus goes to the first problem. Details has the title with a 70 character counter, the condition as radio cards, the category's own fields (selects open as bottom sheets on phones) and the description. Photos takes up to 8 photos by drop, picker, camera or paste, each uploads with progress (a failed one offers Retry), drag or Space and the arrow keys reorder them and the first is badged Cover. Price switches between fixed, negotiable, free and swap, shows similar ads' range and the delivery switch. Location is the Romanian address form with Show the exact location. Contact prefills the account. Preview shows the ad as a grid and a list card and a summary whose Edit links go back to a step; Publish ad spins, then the success view with a bouncing check, View ad, Post another ad and the promotion packages. A failed publish shows an alert and keeps the draft. Completed steps in the stepper are clickable; Back never validates. Every change is saved to local storage after a moment (Draft saved 3 s ago); a reload restores it with an alert and Start over, and photos that only lived in the page are dropped with a note. Discard asks before deleting a draft. On phones the wizard fills the screen under the shell's header, with the compact progress on top and Back / Continue pinned above the safe area. Under reduced motion steps crossfade and the check just appears.

## Installation

```bash
npx wingo-ui@latest add post-listing-wizard
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/post-listing-wizard` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `components/blocks/post-listing-wizard.tsx`
- `components/blocks/post-listing-wizard-data.ts`

npm dependencies: `npm i react-hook-form zod motion lucide-react`

Wingo UI dependencies (installed automatically):

- [Address Input](https://wingo-ui.com/components/address-input) ([Markdown](https://wingo-ui.com/components/address-input.md))
- [Alert](https://wingo-ui.com/components/alert) ([Markdown](https://wingo-ui.com/components/alert.md))
- [Alert Dialog](https://wingo-ui.com/components/alert-dialog) ([Markdown](https://wingo-ui.com/components/alert-dialog.md))
- [Badge](https://wingo-ui.com/components/badge) ([Markdown](https://wingo-ui.com/components/badge.md))
- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Category picker](https://wingo-ui.com/components/category-picker) ([Markdown](https://wingo-ui.com/components/category-picker.md))
- [Currency Input](https://wingo-ui.com/components/currency-input) ([Markdown](https://wingo-ui.com/components/currency-input.md))
- [File Upload](https://wingo-ui.com/components/file-upload) ([Markdown](https://wingo-ui.com/components/file-upload.md))
- [Form Wizard](https://wingo-ui.com/components/form-wizard) ([Markdown](https://wingo-ui.com/components/form-wizard.md))
- [Input](https://wingo-ui.com/components/input) ([Markdown](https://wingo-ui.com/components/input.md))
- [Listing card](https://wingo-ui.com/components/listing-card) ([Markdown](https://wingo-ui.com/components/listing-card.md))
- [Number Input](https://wingo-ui.com/components/number-input) ([Markdown](https://wingo-ui.com/components/number-input.md))
- [Phone Input](https://wingo-ui.com/components/phone-input) ([Markdown](https://wingo-ui.com/components/phone-input.md))
- [Radio Group](https://wingo-ui.com/components/radio-group) ([Markdown](https://wingo-ui.com/components/radio-group.md))
- [Select](https://wingo-ui.com/components/select) ([Markdown](https://wingo-ui.com/components/select.md))
- [Switch](https://wingo-ui.com/components/switch) ([Markdown](https://wingo-ui.com/components/switch.md))
- [Textarea](https://wingo-ui.com/components/textarea) ([Markdown](https://wingo-ui.com/components/textarea.md))
- [Toast](https://wingo-ui.com/components/toast) ([Markdown](https://wingo-ui.com/components/toast.md))
- [usePersistedState](https://wingo-ui.com/components/use-persisted-state) ([Markdown](https://wingo-ui.com/components/use-persisted-state.md))
- [Commerce](https://wingo-ui.com/components/commerce) ([Markdown](https://wingo-ui.com/components/commerce.md))
- [Date utils](https://wingo-ui.com/components/date-utils) ([Markdown](https://wingo-ui.com/components/date-utils.md))
- [Form validation](https://wingo-ui.com/components/form-validation) ([Markdown](https://wingo-ui.com/components/form-validation.md))
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [Navigation](https://wingo-ui.com/components/navigation) ([Markdown](https://wingo-ui.com/components/navigation.md))
- [Relative time](https://wingo-ui.com/components/relative-time) ([Markdown](https://wingo-ui.com/components/relative-time.md))
- [Romanian locations](https://wingo-ui.com/components/ro-locations) ([Markdown](https://wingo-ui.com/components/ro-locations.md))
- [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
// app/(market)/post-ad/page.tsx (the shell lives in the layout with variant="minimal"; mount <Toaster /> once there)
"use client"

import { useRouter } from "next/navigation"
import { PostListingWizard } from "@/components/blocks/post-listing-wizard"

export default function PostAdPage() {
  const router = useRouter()
  return (
    <PostListingWizard
      user={{ name: "Emma Carter", phone: "+40745123456", email: "emma.carter@acme.com", locality: "Cluj-Napoca" }}
      onUpload={async (file, { signal }) => {
        const body = new FormData()
        body.append("photo", file)
        const response = await fetch("/api/photos", { method: "POST", body, signal })
        return response.json() // { url }
      }}
      onPublish={async (draft) => {
        const response = await fetch("/api/listings", { method: "POST", body: JSON.stringify(draft) })
        if (!response.ok) throw new Error("We could not publish your ad. Please try again.")
        return response.json() // { id, url }
      }}
      onCancel={() => router.push("/")}
    />
  )
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `categories?` | `CategoryNode[]` |  | The category tree (POST_LISTING_SAMPLE.categories: the 12 marketplace categories with their subcategories and counts). Only leaves can be picked. |
| `attributes?` | `Record<string, CategoryAttributeDef[]>` |  | The Details fields per leaf category id (POST_LISTING_SAMPLE.attributes: Bicycles, Mobile phones, Apartments). CategoryAttributeDef = { id, label, type: "select" \| "text" \| "number", options?, required?, unit? }. |
| `priceHints?` | `Record<string, { min: number; max: number }>` |  | Similar ads' price range in RON per category id, shown under the price (POST_LISTING_SAMPLE.priceHints: Bicycles 900 to 1,500 RON). |
| `draft?` | `ListingDraft` |  | The ad being written, controlled; pair it with onDraftChange. ListingDraft = { category, categoryPath, title, condition, attributes, description, photos: UploadFile[], priceType, price, currency, location: { county, locality, address?, showExact }, contact: { name, phone, hidePhone, chatOnly }, delivery }. |
| `defaultDraft?` | `ListingDraft` |  | The starting draft, uncontrolled. Default: an empty ad with the contact and the place taken from user (createEmptyListingDraft). POST_LISTING_SAMPLE.draft is the filled l01 bike. |
| `onDraftChange?` | `(draft: ListingDraft) => void` |  | Every change to the draft. |
| `step?` | `PostListingStep` |  | The current step, controlled; pair it with onStepChange. |
| `defaultStep?` | `"category" \| "details" \| "photos" \| "price" \| "location" \| "contact" \| "preview"` | `"category"` | The starting step; the steps before it count as done. The playground fills the l01 bike for every step past the first. |
| `onStepChange?` | `(step: PostListingStep) => void` |  | Called with the new step on every change. |
| `user?` | `{ name: string; phone: string; email: string; locality: string }` |  | The signed-in seller: prefills Contact and the place, shows the email read only (POST_LISTING_SAMPLE.user: Emma Carter, +40745123456, emma.carter@acme.com, Cluj-Napoca). |
| `persistKey?` | `string` | `"post-listing-draft"` | Local storage key of the autosaved draft and step; "" keeps it in memory. The demo uses demo:post-listing and a Delete draft button in the header. |
| `maxPhotos?` | `number` | `8` | The most photos an ad takes; more are rejected with the upload's message. |
| `requirePhoto?` | `boolean` | `true` | Fotografii needs at least one photo to continue. |
| `promotions?` | `{ id: string; label: string; price: number; description?: string; featured?: boolean }[]` |  | The promotion offer after publishing (POST_LISTING_SAMPLE.promotions: No promotion, 7 days 29 RON, 30 days 79 RON Most popular, Auto refresh 15 RON). [] hides it. |
| `ctaTone?` | `"neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Publish ad, View ad and Promote (brand in the examples). |
| `onUpload?` | `(file: File, context: { signal; onProgress }) => Promise<unknown>` |  | Uploads one photo; resolve with { url } so the photo shows after its step and survives a reload. Default: a pretend 1,2 s upload with progress that resolves with an object url. |
| `onPublish?` | `(draft: ListingDraft) => Promise<{ id: string; url: string }>` |  | Publishes the ad. The button spins while it runs; a rejection shows its message in an alert and keeps the draft. Default: a pretend 1,2 s request. |
| `onPromote?` | `(promotion: PostListingPromotion, listing: { id; url }) => (void \| Promise<unknown>)` |  | Buys the chosen package. A rejection shows its message. Default: a pretend request, then a toast. |
| `onCancel?` | `() => void` |  | After Discard deleted the draft (leave the page here). Default: a toast. |
| `defaultPublished?` | `{ id: string; url: string } \| null` |  | Opens on the success view for defaultDraft, as if it had just been published (the promotion example). |
| `labels?` | `Partial<PostListingWizardLabels>` |  | Every visible string (DEFAULT_POST_LISTING_WIZARD_LABELS, Romanian), counted ones as functions; nested validation, categoryPicker, fileUpload, addressInput, phoneInput, currencyInput and listingCard for the composed items. POST_LISTING_WIZARD_LABELS_EN is the English set. |
| `locale?` | `string` | `"en-US"` | Intl locale for prices, counts, sizes and dates. |
| `currency?` | `string` | `"RON"` | The empty draft's currency; the price field switches between RON and EUR. |
| `tone?` | `"neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | The stepper, Continue, the selected category, radio cards, switches and upload progress. |
| `radius?` | `"sm" \| "md" \| "lg"` | `"md"` | The form panel 12 / 16 / 24px, its tiles, the radio cards, the photo tiles and the listing cards. |
| `loading?` | `boolean` | `false` | The stepper and the category tiles as skeletons. |
| `animateIn?` | `boolean` | `true` | The header and the form rise in once when the page mounts on the client (never over server HTML, never with reduced motion). |
| `linkComponent?` | `(props: LinkComponentProps) => ReactNode` |  | The router link for View ad and the terms. Default: the provider's (the shell's), then <a>. |
| `className?` | `string` |  | Classes for the root. |
| `classNames?` | `Partial<Record<"header" \| "panel" \| "wizard" \| "success" \| "promote", string>>` |  | Classes for the parts. |

## Parts

### createEmptyListingDraft (function)

Returns an empty ad for a seller, with the contact and the place filled from their account and the price in the given currency.

### DEFAULT_POST_LISTING_WIZARD_LABELS (constant)

Every English string of the seven steps, the preview, the draft and the publish states. Spread it and override what you translate.

### POST_LISTING_WIZARD_LABELS_EN (constant)

An alias of DEFAULT_POST_LISTING_WIZARD_LABELS, kept so older imports keep working.

### POST_LISTING_SAMPLE (constant)

The demo content: categories, attributes per category, price hints, promotions, the seller, photos, a ready draft and a rough draft. Replace it with your own data.

### POST_LISTING_NOW (constant)

The fixed "now" of the sample (September 24, 2026, 4:40 PM), so the autosave times render the same on server and client.

## Examples

- **Details with errors**: A rushed bike ad: Continue shows every problem and focuses the title.
- **Photos**: Four uploaded photos; drag or use Space and the arrows to reorder, the first is the cover.
- **Preview**: The l01 bike as buyers see it in a grid and a list, with the summary and Edit links.
- **Published, with the promote offer**: The success view with brand actions; pick a package and press Promote.
- **Publish fails**: The pretend server rejects: an alert under the summary, the draft stays.
- **Euro, en-GB**: The price step with a euro amount and en-GB formatting.
- **Loading**: The stepper and the category tiles as skeletons.

## See also

- [Marketplace Shell](https://wingo-ui.com/components/marketplace-shell) ([Markdown](https://wingo-ui.com/components/marketplace-shell.md))
- [Form Wizard](https://wingo-ui.com/components/form-wizard) ([Markdown](https://wingo-ui.com/components/form-wizard.md))
- [Category picker](https://wingo-ui.com/components/category-picker) ([Markdown](https://wingo-ui.com/components/category-picker.md))
- [File Upload](https://wingo-ui.com/components/file-upload) ([Markdown](https://wingo-ui.com/components/file-upload.md))
- [Address Input](https://wingo-ui.com/components/address-input) ([Markdown](https://wingo-ui.com/components/address-input.md))
- [Listing card](https://wingo-ui.com/components/listing-card) ([Markdown](https://wingo-ui.com/components/listing-card.md))

---

Canonical: https://wingo-ui.com/components/post-listing-wizard
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt