Custom components and renderers
Custom components and renderers
Crouton lets you replace any part of the generated UI with your own Vue component β an entire form, a single field, or a table cell. Everything uses the same customComponents registry.
Three overlapping names β which one does what
| Name | Set where | Replaces |
|---|---|---|
layout.view.component | resource.json layout.view | Extra content alongside the form |
fieldInput.options.customComponent | resource.json column | A single form field |
fieldTable.options.customComponent | resource.json column | A single table cell |
All three resolve through the same customComponents registry you pass to CroutonPlugin. The distinction is only where in resource.json you declare the name; the registration pattern is identical.
There is no separate options.customRender β that name does not exist in the current codebase. Use options.customComponent for field-level overrides.
CustomComponentEntry shape
import type { CustomComponentEntry } from '@ghentcdh/crouton-vue';
const entry: CustomComponentEntry = {
tester: customComponentIs('MyComponent', 10), // name + priority
renderer: markRaw(MyComponent), // raw Vue component
};customComponentIs(name, priority) creates a tester function that matches when the resource.json declares that component name. The priority (second arg) determines which tester wins when multiple match β higher wins.
Registration
// src/custom-components.ts
import { customComponentIs, type CustomComponentEntry } from '@ghentcdh/crouton-vue';
import { markRaw } from 'vue';
import RatingInput from './RatingInput.vue';
import RatingStarsRenderer from './RatingStarsRenderer.vue';
export const customComponents: CustomComponentEntry[] = [
{
tester: customComponentIs('rating', 10),
renderer: markRaw(RatingInput),
},
{
tester: customComponentIs('RatingStars', 10),
renderer: markRaw(RatingStarsRenderer),
},
];// src/main.ts
import { CroutonPlugin } from '@ghentcdh/crouton-vue';
import { customComponents } from './custom-components';
app.use(
CroutonPlugin(api, {
router,
customComponents,
defaults: { '$user': currentUser },
}),
);Example: custom field renderer (RatingInput)
A field renderer uses a standard v-model interface: modelValue prop + update:modelValue emit. Define props in a sibling .properties.ts file following the project convention:
// src/RatingInput.properties.ts
import type { PropType } from 'vue';
export const RatingInputProperties = {
modelValue: { type: Number as PropType<number | null>, default: null },
};<!-- src/RatingInput.vue -->
<template>
<div class="flex gap-1">
<button
v-for="star in 5"
:key="star"
type="button"
@click="emit('update:modelValue', star)"
:class="star <= (modelValue ?? 0) ? 'text-yellow-400' : 'text-gray-300'"
style="font-size: 1.5rem; background: none; border: none; cursor: pointer;"
>
β
</button>
</div>
</template>
<script lang="ts" setup>
import { RatingInputProperties } from './RatingInput.properties.js';
const props = defineProps(RatingInputProperties);
const emit = defineEmits<{ 'update:modelValue': [value: number] }>();
</script>Wire it to the rating field in resource.json:
{
"columns": {
"rating": {
"hiddenInTable": false,
"fieldInput": {
"type": "custom",
"options": {
"customComponent": "rating"
}
}
}
}
}The name in options.customComponent ("rating") must match the first argument to customComponentIs('rating', 10). fieldInput.type must be "custom" β omitting it or using another type disables the custom renderer.
Example: custom table cell renderer (RatingStarsRenderer)
A table cell renderer receives the row's full data and the cell value:
<!-- src/RatingStarsRenderer.vue -->
<script lang="ts" setup>
const props = defineProps<{
data: Record<string, unknown>; // full row object
value: number; // cell value
column: string; // column id
options: Record<string, unknown>; // fieldTable.options
}>();
const stars = computed(() => Math.round(props.value ?? 0));
</script>
<template>
<span class="rating-stars">
<span v-for="i in 5" :key="i" :class="i <= stars ? 'filled' : 'empty'">β
</span>
<span class="book-title">{{ (props.data as any).title }}</span>
</span>
</template>Register it for the table cell via fieldTable:
{
"rating": {
"type": "number",
"fieldTable": {
"options": {
"customComponent": "RatingStars"
}
}
}
}Example: extra content alongside the form (layout.view.component)
layout.view.component renders a custom Vue component after the generated form (in the #content-after slot). It does not replace the form. Combine it with container.mode: "page" when you want to show related stats, a preview, or any extra UI next to the edit form.
// resources/book/resource.json
{
"layout": {
"view": {
"container": { "mode": "page" },
"component": "BookEditor"
}
}
}import { CroutonPlugin, customComponentIs } from '@ghentcdh/crouton-vue';
import { markRaw } from 'vue';
import BookEditor from './BookEditor.vue';
app.use(
CroutonPlugin(api, {
customComponents: [
{ tester: customComponentIs('BookEditor', 10), renderer: markRaw(BookEditor) },
],
}),
);BookEditor.vue receives a resource prop (with loadData, save, closeForm, etc.) and all form config props. See resource.json β Display for the full field reference.
Custom JsonForms renderers
For lower-level control (JSON Schema format-based matching rather than name-based), register standard JsonForms renderers:
import { rankWith, isCustomFormat, CroutonPlugin } from '@ghentcdh/crouton-vue';
import { markRaw } from 'vue';
import IsbnInput from './IsbnInput.vue';
app.use(
CroutonPlugin(api, {
renderers: [
{
tester: rankWith(20, isCustomFormat('isbn')),
renderer: markRaw(IsbnInput),
},
],
}),
);The three renderer arrays map to these contexts:
renderersβ create/edit modals and view (readonly) modals. Use for custom formats that should work in all contexts.readonlyRenderersβ view (readonly) modals only, stacked on top ofrenderers.cellRenderersβ table cell rendering.
Use renderers / readonlyRenderers / cellRenderers for format-based matching; use customComponents for name-based matching. Both approaches are available and complementary.