Quick Start
Quick Start
Get annotation editing running in a Vue 3 app in under 10 minutes.
Install
pnpm add @ghentcdh/annotation-vue @ghentcdh/annotation-core @ghentcdh/annotated-text @ghentcdh/w3c-utilsImport the CSS once in your app entry point:
import '@ghentcdh/annotation-vue/styles.css';Concepts
Before adding a component, you need three things:
AnnotationDefConfig โ tells the library where your annotation namespace lives:
import { type AnnotationDefConfig } from '@ghentcdh/annotation-vue';
const config: AnnotationDefConfig = {
baseUrl: 'https://api.example.com/',
app: 'my-app',
prefix: 'my-prefix',
};AnnotationDefinition[] โ the annotation types available in the editor (label, colour, views for table/form/detail display, etc). Load these with provideAnnotationDefinitions from @ghentcdh/annotation-vue, or build them manually.
SourceModel[] โ the text sources to annotate. Each source is a plain object:
import { type SourceModel } from '@ghentcdh/annotation-vue';
const sources: SourceModel[] = [
{
id: 'original',
uri: 'https://example.com/texts/1',
type: 'text',
content: {
label: 'Original',
text: 'Lorem ipsum dolor sit amet.',
textDirection: 'ltr',
processingLanguage: 'en',
},
},
];Minimal example
<template>
<AnnotationEditor
:sources="sources"
:annotations="editorAnnotations"
:annotation-definitions="definitions"
:annotation-transformer="transformer"
@create:annotation="onCreate"
@update:annotation="onUpdate"
@delete:annotation="onDelete"
/>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { AnnotationEditor } from '@ghentcdh/annotation-vue';
import { parseAnnotations, editorAnnotationSchema, type AnnotationTransformer, type EditorAnnotation } from '@ghentcdh/annotation-vue';
import { provideAnnotationDefinitions } from '@ghentcdh/annotation-vue';
import { type W3CAnnotation } from '@ghentcdh/w3c-utils';
import { type AnnotationDefConfig, type SourceModel } from '@ghentcdh/annotation-vue';
const config: AnnotationDefConfig = {
baseUrl: 'https://api.example.com/',
app: 'my-app',
prefix: 'my-prefix',
};
// Load annotation type definitions from JSON configs bundled with your app
const resourceFolder = import.meta.glob('./annotation-configs/*.json', { eager: true });
const { definitions } = provideAnnotationDefinitions({ config, resourceFolder });
const sources: SourceModel[] = [
{
id: 'original',
uri: 'https://example.com/texts/1',
type: 'text',
content: {
label: 'Original',
text: 'Lorem ipsum dolor sit amet.',
textDirection: 'ltr',
processingLanguage: 'en',
},
},
];
// Converts between your domain model and EditorAnnotation
const transformer: AnnotationTransformer<W3CAnnotation> = {
parse: (raw) => editorAnnotationSchema.parse({ id: raw.id, /* map fields */ }),
format: (annotation, isNew) => ({ id: annotation.id, /* map fields */ }) as W3CAnnotation,
};
const rawAnnotations = ref<W3CAnnotation[]>([]);
// Convert raw annotations to the editor's internal format (parse + resolve links)
const editorAnnotations = computed(() => parseAnnotations(transformer, rawAnnotations.value));
const onCreate = async (annotation: W3CAnnotation) => {
// persist to your API, then push to local state
rawAnnotations.value = [...rawAnnotations.value, annotation];
};
const onUpdate = async (annotation: W3CAnnotation) => {
rawAnnotations.value = rawAnnotations.value.map((a) =>
a.id === annotation.id ? annotation : a,
);
};
const onDelete = async (annotation: W3CAnnotation) => {
rawAnnotations.value = rawAnnotations.value.filter((a) => a.id !== annotation.id);
};
</script>Prefer SmartAnnotationEditor
If your data comes from an API, SmartAnnotationEditor handles loading, caching, and adapter wiring for you with less boilerplate.
Read-only mode
Pass :readonly="true" to AnnotationEditor to display annotations without allowing edits, or use SmartAnnotationEditor with :readonly="true":
<SmartAnnotationEditor
:loader="loader"
:source-uris="sourceUris"
:readonly="true"
/>Next steps
- AnnotationEditor โ full props, events, and examples
- SmartAnnotationEditor โ loader-driven component with built-in data fetching