ItcImageCarousel (itc-carousel)

A Vue 3 + Quasar component for product-style image galleries: large QImg preview, synced thumbnails (row or vue3-carousel strip with chevrons), optional remove control, and an add slot for your uploader. Inspired by ProductImageCarousel in boilerplate-quasar-v2 (without a built-in FilesUploader).

Features

• ✅ Main preview - Large image with configurable height
• ✅ Thumbnail row - Click to change main image; optional #add slot
• ✅ Carousel strip mode - vue3-carousel for thumbs + prev/next (responsive breakpoints)
• ✅ Remove control - Optional delete on main image + remove-image emit
• ✅ Generic items - ItcCarouselImage (src, optional thumbSrc, optional id)
• ✅ TypeScript - Exported types and typed emits
• ✅ Plugin install - app.use(itcCarousel) registers <ItcImageCarousel> globally

Installation

npm install itc-carousel vue3-carousel
# or
pnpm add itc-carousel vue3-carousel

Also install peers vue and quasar in your app if not already present.

Requirements

• Vue 3.x
• Quasar 2.x
• vue3-carousel ^0.3.4

These are peer dependencies (except vue3-carousel, which should be installed alongside the package). The library entry re-exports vue3-carousel/dist/carousel.css via src/index.ts; your bundler must resolve vue3-carousel normally.

Usage

Basic example

<script setup lang="ts">
import { ref } from 'vue'
import { ItcImageCarousel } from 'itc-carousel'
import type { ItcCarouselImage } from 'itc-carousel'

const images = ref<ItcCarouselImage[]>([
  { id: 1, src: 'https://example.com/large-1.jpg', thumbSrc: 'https://example.com/thumb-1.jpg' },
  { id: 2, src: 'https://example.com/large-2.jpg' }
])

function onRemove (item: ItcCarouselImage) {
  images.value = images.value.filter((i) => i.id !== item.id)
}
</script>

<template>
  <ItcImageCarousel
    :images="images"
    show-remove-button
    @remove-image="onRemove"
  >
    <template #add>
      <q-btn flat dense icon="o_add" label="Add" @click="/* your uploader */" />
    </template>
  </ItcImageCarousel>
</template>

Carousel strip for thumbnails

<template>
  <ItcImageCarousel
    :images="images"
    show-sub-image-slider
    show-remove-button
    @remove-image="onRemove"
  />
</template>

Global registration (plugin)

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import { itcCarousel } from 'itc-carousel'

const app = createApp(App)
app.use(itcCarousel) // registers <ItcImageCarousel>
app.mount('#app')

Mapping boilerplate / API media

function toCarouselImages (rows: YourMediaRow[]): ItcCarouselImage[] {
  return rows.map((row) => ({
    id: row.id,
    src: row.generated_conversions_url?.['720x1280'] || row.full_url,
    thumbSrc: row.generated_conversions_url?.['90x160'] || row.full_url
  }))
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | images | ItcCarouselImage[] | [] | Images to display | | showSubImageSlider | Boolean | false | Use vue3-carousel for thumbs + chevrons | | showRemoveButton | Boolean | false | Show remove on main preview | | mainHeight | Number | 300 | Main preview height (px) | | breakpoints | Object | { 300: { itemsToShow: 5, snapAlign: 'center' } } | Passed to Carousel | | placeholderSrc | String | built-in SVG | Fallback when empty or missing src |

See src/components/ItcImageCarousel.vue for the full prop list.

Events

| Event | Payload | Description | |-------|---------|-------------| | remove-image | ItcCarouselImage | Emitted when remove is clicked on the main preview |

Slots

| Slot | Description | |------|-------------| | add | Shown after row thumbnails when show-sub-image-slider is false (e.g. wrap FilesUploader / QBtn) |

Path aliases

This package supports src/ imports during development (tsconfig.json + vite.config.ts):

// ✅ Good — path alias
import type { ItcCarouselImage } from 'src/types'
import ItcImageCarousel from 'src/components/ItcImageCarousel.vue'

// ❌ Avoid — relative paths (still work, not preferred for internal dev)
import type { ItcCarouselImage } from '../types'

Consumers typically import from the package root:

import { ItcImageCarousel, itcCarousel } from 'itc-carousel'
import type { ItcCarouselImage } from 'itc-carousel'

Project structure

├─ src/
│   ├─ components/
│   │   └─ ItcImageCarousel.vue
│   ├─ types.ts            # ItcCarouselImage
│   ├─ index.ts            # Main export (+ carousel.css side effect)
│   ├─ plugin.ts           # Global install plugin
│   └─ vue-shim.d.ts       # Vue type declarations
├─ dist/                   # Build output (generated)
├─ package.json
├─ tsconfig.json
├─ tsconfig.build.json
└─ vite.config.ts

Building

Build for production

pnpm run build
# or
npm run build

This will:

• Compile Vue SFCs and TypeScript via Vite
• Generate ES Modules (.js) and CommonJS (.cjs) with preserved layout under dist/
• Run vue-tsc -p tsconfig.build.json for .d.ts files

Build output structure

dist/
├─ src/
│   ├─ index.js / index.cjs
│   ├─ index.d.ts
│   ├─ components/
│   │   └─ ...
│   └─ ...
└─ itc-carousel.css        # may be emitted (scoped + entry CSS)

Exact chunk names follow Vite/Rollup; see package.json exports for entry points.

Testing locally

Option 1: Using pnpm link (recommended)

1. In your plugin directory:

   pnpm link --global

2. In your test project:

   pnpm link --global itc-carousel

3. Install vue3-carousel in the test project (peer).

4. Use in your project:

   <script setup>
   import { ItcImageCarousel } from 'itc-carousel'
   </script>

Option 2: Using file path

1. In your test project's package.json:

   {
     "dependencies": {
       "itc-carousel": "file:../path/to/itc-carousel",
       "vue3-carousel": "^0.3.4"
     }
   }

2. Build the library, then install:

   cd ../path/to/itc-carousel
   npm run build
   cd -
   pnpm install

3. Use in your project:

   <script setup>
   import { ItcImageCarousel } from 'itc-carousel'
   </script>

Unlinking after local development

For Option 1 (pnpm / npm link)

1. In your test project, unlink:

   pnpm unlink --global itc-carousel
   # or
   npm unlink itc-carousel

2. Reinstall from npm when published:

   pnpm add itc-carousel vue3-carousel

3. Optionally in the plugin directory:

   pnpm unlink --global

For Option 2 (file path)

1. Remove the file: dependency from package.json.

2. Reinstall from npm:

   pnpm add itc-carousel vue3-carousel

Troubleshooting unlinking

• Clean reinstall:

  rm -rf node_modules
  pnpm install

• Check symlinks:

  ls -la node_modules/itc-carousel

• Verify resolution:

  pnpm why itc-carousel
  npm ls itc-carousel

Development workflow

For active development with auto-rebuild:

pnpm run dev
# or
npm run dev

Restart your app's dev server if it does not pick up dist/ changes.

Publishing to npm

Before publishing

1. Update package.json:

   • Set correct name (unique on npm)

   • Bump version (semver)

   • Fill description, keywords, author, license

   • Verify files includes what you publish:

     {
       "files": ["dist", "README.md"]
     }

2. Build:

   npm run build

3. Test locally (see Testing locally above).

Publishing steps

1. Login:

   npm login

2. Verify:

   npm whoami
   npm pack --dry-run

3. Publish:

   npm publish

   For a scoped package:

   npm publish --access public

4. Verify on npm:
   https://www.npmjs.com/package/itc-carousel

Version management

npm version patch
npm version minor
npm version major

Then:

npm publish

Configuration

External dependencies

By default vue, quasar, and vue3-carousel (including vue3-carousel/... paths) are external and not bundled into the library.

vite.config.ts (conceptually):

function isVue3Carousel (id: string) {
  return id === 'vue3-carousel' || id.startsWith('vue3-carousel/')
}

rollupOptions: {
  external: (id) =>
    id === 'vue' ||
    id === 'quasar' ||
    isVue3Carousel(id) ||
    id.startsWith('@quasar/') ||
    id.startsWith('quasar/')
}

Add more packages to that predicate if you introduce new runtime dependencies that must stay external.

Build formats

The build targets ESM and CJS via rollupOptions.output in vite.config.ts.

Troubleshooting

TypeScript errors

• Cannot find module src/...: Restart the TS server; align paths in tsconfig.json with Vite resolve.alias.

Build errors

• Rollup failed to resolve import: Mark the dependency as external in vite.config.ts if it must not be bundled.
• Missing dist: Run npm run build in itc-carousel before file: or linked installs.

Import errors in the test project

• Ensure npm run build completed successfully.
• Install vue3-carousel in the app.
• Verify package.json exports match your import path.

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Build and test locally
5. Submit a pull request

Happy coding! 🚀