Native UI view

A UI view can be created as a Vue JS component.
In Neos Studio set the switch "Native UIView" to "Yes" in the UI view editor to use this approach. So you cannot edit the xml template of the view, but you can use the full flexibility of Vue JS to create your view.
In the toolbar you can create the typescript project and the Vue component by clicking on the button "Create Native UIView". This will create a new folder "nativeUIs" in the current module folder and add a new Vue component with the name of the view. You can then edit this component to create your view.

Quick start

1. Create a new UI view and set "Native UIView" to "Yes".
2. Click "Create Native UIView" in the toolbar to generate the Vue component.
3. Open the generated Vue component in your editor

<template></template>

<script setup lang="ts">
import OrderUI from '@cluster/views/OrderUI/OrderUI'
import OrderUIViewModel from '@cluster/views/OrderUI/OrderUIViewModel'
import { NeosAutomation, NeosLayout, NeosStyle, useFormat } from '@neos/app'
import { ApplicationContext } from '@neos/core'
import { Device, ResourceManager } from '@neos/shared'

// A native UI View receives this set of props
// - mainViewModel: the view model of the component, typed according to the component's view model class
// - applicationResourceManager: allows to retrieve string resources
// - applicationContext: allows to retrieve value from the application context
// - device: allows to retrieve information about the current device (ex: <template v-if="device.hasLargeScreenWidth">)
// - you can also add the name of a sub view model as a prop if your component has sub views (ex: mySubUIViewModel: MySubUIViewModel)
// You can remove any of these props if you don't need them.
const props = defineProps<{
  mainViewModel: OrderUIViewModel
  applicationResourceManager: ResourceManager
  applicationContext: ApplicationContext
  device: Device
}>()

// if your composant need to format data use format function (ex: format((mainViewModel.current ?? {}).myProperty) )
const format = useFormat()

// If your component needs to use directive like v-neos-layout, v-neos-style or v-neos-automation, you need to import them.
const vNeosLayout = NeosLayout
const vNeosStyle = NeosStyle
const vNeosAutomation = NeosAutomation
</script>

4. Import and use Neos components as needed to build your UI.
5. Save your changes

How to access sub UI view models

If your UI view has sub views, you can access their view models by adding them as props.

For example, if your UI view has a UI view 'OrderUI' with a sub view 'orderDetailList' which has a sub view 'orderDetailEventList', you can access their view models by adding them as props like this:

<script setup lang="ts">
import OrderDetailEventUIViewModel from '@cluster/views/OrderDetailEventUI/OrderDetailEventUIViewModel'
import OrderDetailUIViewModel from '@cluster/views/OrderDetailUI/OrderDetailUIViewModel'
import OrderUIViewModel from '@cluster/views/OrderUI/OrderUIViewModel'
import {
  NeosAutomation,
  NeosLayout,
  NeosStyle,
  useFormat,
} from '@neos/app'
import { ApplicationContext } from '@neos/core'
import { Device, ResourceManager } from '@neos/shared'

const props = defineProps<{
  mainViewModel: OrderUIViewModel,
  orderDetailListViewModel: OrderDetailUIViewModel, // this is the view model of a sub view 'orderDetailList'
  orderDetailListViewModel_orderDetailEventListViewModel: OrderDetailEventUIViewModel, // this is the view model of a sub view 'orderDetailEventList' inside the sub view 'orderDetailList'
  applicationResourceManager: ResourceManager,
  applicationContext: ApplicationContext,
  device: Device
}>()

The name of the prop for a sub view model is the concatenation of the names of the parent views and the sub view, followed by "ViewModel". In this example, the prop name for the 'orderDetailEventList' sub view model is 'orderDetailListViewModel_orderDetailEventListViewModel'.

How to use Neos directives

For example, if you want to use the v-neos-layout directive in your component, you need to import it and assign it to a variable like this:

<script setup lang="ts">
import { NeosLayout } from '@neos/app'

const vNeosLayout = NeosLayout
</script>

What file can I join to my UI view component?

You can add typescript files, js files, css files or other vue files in the same folder as your UI view component. You can then import them in your UI view component and use them as needed.

Warning

You cannot add local assets (ex: images) in the same folder as your UI view component. You must use the image component instead.

Components and Directives exported By @neos/app

These exports are generic UI building blocks. They are the right choice when the component does not need to understand Neos-specific ViewModel behavior.

Layout And Structure

Export	Use it for
ButtonsLayout	Arrange action buttons with consistent spacing and wrapping.
Card	Group a related piece of content in a framed container.
Divider	Separate sections visually without introducing extra layout structure.
GridLayout	Build form grids and responsive two-dimensional layouts.
GroupBox	Present a titled logical section of a form or page.
HorizontalLayout	Arrange children in a row with Neos spacing and alignment conventions.
Splitter	Build resizable split panes.
SplitterPanel	Define an individual pane inside Splitter.
TabItem	Define a tab entry for Tabs.
Tabs	Switch between sections without leaving the current screen.
VerticalLayout	Arrange children in a column with Neos spacing and alignment conventions.

Actions, Identity, And Small UI Elements

Export	Use it for
Avatar	Show a user or entity identity thumbnail.
Badge	Display counts, statuses, or short semantic markers.
Button	Trigger a primary, secondary, ghost, link, or icon action.
Chip	Show a small labeled token, often for filters or metadata.
DocumentationButton	Open contextual documentation attached to a field or action.
Image	Render a named image or icon from the resource set.
Text	Render text with consistent typography, weight, and truncation behavior.

Inputs And Editing Controls

Export	Use it for
BooleanCombobox	Choose between boolean values with a select-style control.
DynamicCheckbox	Render a checkbox whose state and behavior are driven dynamically.
DynamicCombobox	Render a combobox whose options are loaded or derived dynamically.
InputColor	Edit color values.
InputDate	Edit date values.
InputDateTime	Edit date and time values.
InputNumber	Edit numeric values.
InputPassword	Edit password or secret text values.
InputSliderDiscrete	Edit single-value or range-value selections from a discrete numeric list.
InputTime	Edit time values.
Textbox	Edit free-form text with labels, validation messaging, and optional adornments.

Content, Data, And Visualization

Export	Use it for
Carousel	Cycle through cards, media, or other repeated items.
Chart	Display quantitative visualizations.
HtmlViewer	Render sanitized HTML content.
LoadDataOnScroll	Trigger incremental loading while the user scrolls.
MarkdownViewer	Render markdown content inside the UI.
Timeline	Display chronological entries or progression steps.
TreeView	Display hierarchical structures with expand and collapse interactions.
VirtualRepeat	Render very large repeated collections using virtualization.

Overlays And Feedback

Export	Use it for
Message	Show inline informational, warning, success, or error messages.
Modal	Show blocking overlay content with header, body, and footer slots.
PopoverWithTarget	Show anchored contextual content attached to a target element.
ProgressBar	Show linear task progress.
Spinner	Show background activity or short-lived loading states.

Design-System Directives

These directives are also re-exported by @neos/app. Register them with Vue and use the kebab-case directive names shown below.

Export	Template name	Use it for
NeosAutomation	v-neos-automation:*	Add automation and test metadata to DOM nodes.
NeosGrid	v-neos-grid:*	Set row and column spans for children inside grid layouts.
NeosLayout	v-neos-layout:*	Apply layout-related sizing, margin, padding, and alignment hints.
NeosStyle	v-neos-style:*	Apply targeted style tokens such as colors, radii, and hover styles.
NeosTooltip	v-neos-tooltip:text	Attach or update a tooltip on a node.

Common examples:

<VerticalLayout v-neos-layout:height="`fill`" v-neos-layout:min-height="320">
  <Button v-neos-style:hover-color="'white'" label="Open" />
  <div v-neos-tooltip:text="helpText">Hover me</div>
  <div v-neos-grid:colspan="2">Wide cell</div>
</VerticalLayout>

App-Specific Components Exported By @neos/app

These components are Neos-aware wrappers or higher-level UI flows. Prefer them over the lower-level design-system primitives when you are working with ViewModels, generated UIs, frame navigation, or common business interactions.

Actions, Menus, And Top-Level Screen Controls

Export	Use it for
ActionButton	Render a ViewModel-driven action, including icon, badge, loading state, dropdown behavior, or split-button behavior.
ActionPanel	Host a group of related actions for the current screen or selection.
CustomViewButton	Open or trigger a custom view action tied to the current Neos context.
GlobalSearchButton	Open the global search experience from a toolbar or header.
GlobalSearchInput	Enter and trigger global search queries.
MenuButton	Open a contextual menu based on Neos action definitions.
MethodButton	Trigger a method-oriented action exposed by the backing ViewModel.
QuickSearch	Provide compact, immediate search input, optionally with AI mode.
ToggleOverlayButton	Toggle a modal or popover identified by overlay id.
Toolbar	Render the standard top action area for a view.
UserButton	Show the current user entry point and related actions.

Filters, Search, And Lookup Flows

Export	Use it for
CustomViewPicker	Switch between available custom views for the current context.
FilterBar	Show the main filter area, including input mode or editable-chip mode.
FilterBuilder	Build complex conditions, groups, and named filters.
FilterChips	Show active filters as removable chips.
Lookup	Resolve references, exhaustive lists, or search-backed lookups with suggestions and modal fallback.
LookupModal	Display the modal part of the lookup flow directly.
PaginationBar	Navigate paged result sets with application-specific behavior.

Form Labels, Validation, And Property-Bound Fields

Export	Use it for
BoundDocumentationButton	Show documentation linked to a bound property.
BoundText	Render text that is already connected to ViewModel or resource-driven behavior.
BooleanFormField	Edit a boolean model property with standard Neos form-field behavior.
ColorFormField	Edit a color property through the standard field wrapper.
DateFormField	Edit a date property through the standard field wrapper.
DateTimeFormField	Edit a date-time property through the standard field wrapper.
EnumFormField	Edit an enum or list-backed property through the standard field wrapper.
FileFormField	Edit a file-backed property through the standard field wrapper.
ImageFormField	Edit an image-backed property through the standard field wrapper.
Label	Render the standard field label used by generated forms.
LocalizableStringFormField	Edit a localizable string property through the standard field wrapper.
LookupFormField	Edit a reference or lookup-backed property through the standard field wrapper.
MaskFormField	Edit a masked text property through the standard field wrapper.
NumberCalculableFormField	Edit a calculable numeric property through the standard field wrapper.
NumberFormField	Edit a numeric property through the standard field wrapper.
PasswordFormField	Edit a password property through the standard field wrapper.
SliderDiscreteFormField	Edit a numeric or numeric-range property through a discrete slider field.
StringArrayFormField	Edit a string-array property through the standard field wrapper.
StringFormField	Edit a string property through the standard field wrapper.
TimeFormField	Edit a time property through the standard field wrapper.
ValidationMessage	Display validation feedback for a field or an interaction flow.

Data Presentation, Navigation, And Screen Containers

Export	Use it for
Context	Provide the application context expected by nested Neos components.
Datagrid	Display editable or read-only tabular data, with responsive card mode, grouping, row detail, export, and drag-and-drop support.
FramesContainer	Render frame or tab navigation and the currently active frame content.
IdentifiedModal	Render a modal controlled by a ViewModel overlay id instead of local component state.
IdentifiedPopover	Render a popover controlled by a ViewModel overlay id.
ReportDesigner	Host the Neos report-design experience.
ReportViewer	Host the Neos report-viewing experience.
Sidebar	Render the standard application side navigation or contextual side panel.
ViewContainer	Render the current frame content for the active view.
WebView	Embed web content inside a Neos-managed screen.

File, Image, And Load Behaviors

Export	Use it for
InputFile	Select or manage file input values in a Neos screen.
InputImage	Select or manage image input values in a Neos screen.
ViewModelLoadDataOnScroll	Trigger ViewModel-driven incremental loading while scrolling.

App Directive Exported By @neos/app

Export	Template name	Use it for
NeosDragdrop	v-neos-dragdrop:*	Add drag sources, drop zones, file drops, and custom drag payload handling to any element.

Supported directive arguments:

Argument	Expected value	Behavior
draggable	boolean	Sets the native draggable attribute.
data	string or any object	Stores drag payload as plain text or as an internal object.
dragstart	(args) => void	Called when a drag starts.
dragover	(args) => boolean	Called during dragover. Return true to allow dropping and call preventDefault().
dragenter	(args) => void	Called when the dragged item enters the drop zone.
dragleave	(args) => void	Called when the dragged item leaves the drop zone.
dragend	(args) => void	Called when the drag operation ends.
drop	(args) => void	Called when the payload is dropped.

The drag and drop argument helpers let you:

• Read plain-text payloads with getStringData()
• Read in-memory object payloads with getInternalObjectData()
• Detect dropped files with hasFiles()
• Read dropped files with getFiles() inside drop

Example:

<script setup lang="ts">
import { NeosDragdrop, type DropEventArgs } from '@neos/app'

function allowDrop() {
  return true
}

function handleDrop(args: DropEventArgs) {
  if (args.hasFiles()) {
    const files = args.getFiles()
    console.log(files)
  }
}
</script>

<template>
  <div
    v-neos-dragdrop:draggable="true"
    v-neos-dragdrop:data="'customer:42'"
    v-neos-dragdrop:dragover="allowDrop"
    v-neos-dragdrop:drop="handleDrop"
  >
    Drop here
  </div>
</template>

Typical Screen Recipes

Generic Form Screen

Use this pattern when you are building a plain form without advanced ViewModel orchestration:

<template>
  <VerticalLayout space="large">
    <Heading :level="1">Customer</Heading>
    <GroupBox title="Profile">
      <GridLayout :columns="2">
        <Textbox label="First name" />
        <Textbox label="Last name" />
        <InputDate label="Birth date" />
        <InputColor label="Favorite color" />
      </GridLayout>
    </GroupBox>
    <ButtonsLayout>
      <Button variant="primary" label="Save" icon="validate" />
      <Button variant="ghost" label="Cancel" />
    </ButtonsLayout>
  </VerticalLayout>
</template>

ViewModel-Driven List Screen

Use this pattern when a screen needs standard Neos list behaviors such as filters, lookups, row actions, overlays, and tabs:

<template>
  <VerticalLayout v-neos-layout:height="`fill`">
    <Toolbar />
    <FilterBar />
    <QuickSearch />
    <Datagrid :editable="true" :groupable="true" :column-picker="true" />
    <PaginationBar />
    <IdentifiedModal overlay-id="details">
      <template #header>
        <Heading :level="2">Details</Heading>
      </template>
      <template #body>
        <Lookup />
      </template>
    </IdentifiedModal>
  </VerticalLayout>
</template>

Practical Guidance For Developers

1. Keep layout responsibilities in VerticalLayout, HorizontalLayout, GridLayout, and the v-neos-layout directive.
2. Keep screen-specific interaction logic in app components and avoid rebuilding standard filter, lookup, and datagrid flows from primitives.
3. Prefer overlay identifiers and existing toolbar or action abstractions over custom modal state when the screen already uses Neos ViewModels.
4. Reach for NeosDragdrop instead of custom DOM listeners when drag-and-drop behavior should stay aligned with the rest of the package.