Custom Renderers

NOTE

The photo album includes several major parts in its component structure. These are: container, row, column, and photo renderers. You can customize each of them with metadata properties to fit your requirements.

container-renderer

Allows providing a custom single root component to render the container. The component should define defineProps<ContainerRendererMetadata>() and contain a default <slot /> for rendering the descendant content.

Type

Type	Default Value	Required
Component <ContainerRendererMetadata>	undefined	No

type PhotoRendererMetadata = {
  photos: Photo[]
  layoutOptions: LayoutOptions
}

type LayoutOptions = RowsLayoutOptions | ColumnsLayoutOptions

type CommonLayoutOptions = {
  spacing: number
  padding: number
  containerWidth: number
  sizes?: ResponsiveSizes
}

type RowsLayoutOptions = CommonLayoutOptions & {
  layout: 'rows'
  targetRowHeight: number
  rowConstraints: RowConstraints
}

type ColumnsLayoutOptions = CommonLayoutOptions & {
  layout: 'columns' | 'masonry'
  columns: number
}

Usage

App.vue

<script setup lang="ts">
import CustomContainer from './CustomContainer.vue'
</script>

<template>
  <PhotoAlbum :container-renderer="CustomContainer" />
</template>

CustomContainer.vue

<script setup lang="ts">
import { type ContainerRendererMetadata } from 'vue-photo-album'

defineProps<ContainerRendererMetadata>()
</script>

<template>
  <div class="custom-container">
    <slot />
  </div>
</template>

<style>
.custom-container {
  position: relative;
  padding: 15px;
  border: 1px solid teal;
  border-radius: 10px;
  overflow: hidden;
}
</style>

Example

row-renderer

Allows providing a custom single root component to render each row. The component should define defineProps<RowRendererMetadata>() and contain a default <slot /> for rendering the descendant content.

Type

Type	Default Value	Required
Component <RowRendererMetadata>	undefined	No

type RowRendererProps = {
  layoutOptions: RowsLayoutOptions
  rowData: { photo: Photo; layout: PhotoLayout }[]
  rowIndex: number
  rowsCount: number
}

type PhotoLayout = {
  width: number
  height: number
  index: number
  photoIndex: number
  photosCount: number
}

Usage

App.vue

<script setup lang="ts">
import CustomRow from './CustomRow.vue'
</script>

<template>
  <PhotoAlbum
    layout="rows"
    :row-renderer="CustomRow"
  />
</template>

CustomRow.vue

<script setup lang="ts">
import { type RowRendererMetadata } from 'vue-photo-album'

defineProps<RowRendererMetadata>()
</script>

<template>
  <div class="custom-row">
    <slot />
  </div>
</template>

<style>
.custom-row {
  position: relative;
  padding: 15px;
  border: 1px solid teal;
  border-radius: 10px;
  overflow: hidden;
}
</style>

Example

column-renderer

Allows providing a custom single root component to render each column. The component should define defineProps<ColumnRendererMetadata>() and contain a default <slot /> for rendering the descendant content.

Type

Type	Default Value	Required
Component <ColumnRendererMetadata>	undefined	No

type ColumnRendererMetadata = {
  layoutOptions: ColumnsLayoutOptions
  columnData: { photo: Photo; layout: PhotoLayout }[]
  columnIndex: number
  columnsCount: number
  columnsGaps?: number[]
  columnsRatios?: number[]
}

type PhotoLayout = {
  width: number
  height: number
  index: number
  photoIndex: number
  photosCount: number
}

Usage

App.vue

<script setup lang="ts">
import CustomColumn from './CustomColumn.vue'
</script>

<template>
  <PhotoAlbum
    layout="columns"
    :column-renderer="CustomColumn"
  />
</template>

CustomColumn.vue

<script setup lang="ts">
import { type ColumnRendererMetadata } from 'vue-photo-album'

defineProps<ColumnRendererMetadata>()
</script>

<template>
  <div class="custom-column">
    <slot />
  </div>
</template>

<style>
.custom-column {
  position: relative;
  padding: 15px;
  border: 1px solid teal;
  border-radius: 10px;
  overflow: hidden;
}
</style>

Example

photo-renderer

A custom single root component to render each photo. The component should define defineProps<PhotoRendererMetadata>() and optionally contain a default for rendering the <img> tag.

Type

Type	Default Value	Required
Component <PhotoRendererMetadata>	undefined	No

type PhotoRendererMetadata = {
  imageProps: ImgHTMLAttributes
  photo: Photo
  layout: PhotoLayout
  layoutOptions: LayoutOptions
  clickable?: boolean
}

Usage

App.vue

<script setup lang="ts">
import CustomPhoto from './CustomPhoto.vue'
</script>

<template>
  <PhotoAlbum
    layout="rows"
    :column-renderer="CustomPhoto"
  />
</template>

CustomPhoto.vue

<script setup lang="ts">
import { type PhotoRendererMetadata } from 'vue-photo-album'

defineProps<PhotoRendererMetadata>()
</script>

<template>
  <div class="custom-photo">
    <div class="custom-photo__img">
      <slot />
    </div>
  </div>
</template>

<style>
.custom-photo {
  position: relative;
  padding: 15px;
  border: 1px solid teal;
  border-radius: 10px;
  overflow: hidden;
}

.custom-photo__img {
  position: absolute;
  inset: 10px;
  border-radius: 5px;
  overflow: hidden;
}
</style>

Example