# API service reference

> NgxViewBuilderApiService, the one service a host application talks to. How calls reach the view, and every method by area with arguments, return values and examples.

Source: https://ngxviewbuilder.io/developers/api-service

`NgxViewBuilderApiService` is the one service your application talks to. Inject it anywhere, in a page component, a resolver, a service of your own, and use it to read and change the view on screen, react to what happens in it, and plug your own functions, validators, elements and icons in.

```ts
import { inject } from '@angular/core';
import { NgxViewBuilderApiService } from '@ngxviewbuilder/runtime';

export class ClientPage {
  private readonly api = inject(NgxViewBuilderApiService);

  async save(): Promise<void> {
    const result = await this.api.validateData();
    if (result.isValid) {
      await this.clients.save(this.api.getData());
    }
  }
}
```

An application that hosts the builder imports the same service from `@ngxviewbuilder/designer`. It is the same class.

## How a call reaches the view

You always inject the root service. What it talks to depends on what is on screen:

| On screen | Calls about the view (values, structure, elements, validation) go to | Registrations (functions, validators, elements, icons, theme) go to |
| --- | --- | --- |
| `<ngx-view-builder-runtime>` | that runtime view | the root and every runtime view, now and later |
| several runtime views | the one created last | the root and every runtime view |
| `<nvb-scope>` | the scope | the root and every scope |
| `<ngx-view-builder-designer>` | the view being edited (the builder owns it) | the root, the builder and its Preview |
| nothing yet | the root itself | the root; views created later pick them up |

Two things follow from that table. You can register everything at startup, before any view exists, and every view gets it. And you never need a reference to a particular runtime, because the root forwards. When several views render at once, every event still reaches the root and carries `elementName` and `elementDataPath`, which is how you tell them apart.

::: tip Waiting for a view
Values and elements exist once the view has rendered. Subscribe to `onAfterRender`, or call the API from a button or an event handler, rather than straight from your constructor.
:::

## Reading this reference

Each page groups the methods of one area. Every method shows its signature, what it does, an example, and what it returns. Types are written in TypeScript; `IStructure` is the view JSON described in [Structure JSON](https://ngxviewbuilder.io/developers/structure-json).

| Page | What it covers |
| --- | --- |
| [Structure & settings](https://ngxviewbuilder.io/developers/api/structure) | Read, replace and patch the view definition and its settings |
| [Data & values](https://ngxviewbuilder.io/developers/api/data) | Form data, single values, server errors, the dirty flag |
| [Elements](https://ngxviewbuilder.io/developers/api/elements) | Finding elements, reading and writing their properties, the element handle, rows of repeaters, element defaults |
| [Validation & lifecycle](https://ngxviewbuilder.io/developers/api/validation) | Validating the view or any structure, toasts, render and completion notifications |
| [Data sources & variables](https://ngxviewbuilder.io/developers/api/data-sources) | Reloading sources, host sources, websocket authorization, runtime variables and external context |
| [Language & theme](https://ngxviewbuilder.io/developers/api/language-theme) | Language, locale, translations, UI dictionaries, theme modes, tokens and custom CSS |
| [Extensions](https://ngxviewbuilder.io/developers/api/extensions) | Expression functions, validator types, custom elements and properties, icons, table cells |
| [Builder, templates & tables](https://ngxviewbuilder.io/developers/api/builder) | Template library, element library, table settings and filters, builder tabs |

Events have their own page: [Events reference](https://ngxviewbuilder.io/developers/events).

## Every method at a glance

| Area | Methods |
| --- | --- |
| Structure | [`getStructure`](https://ngxviewbuilder.io/developers/api/structure#getstructure) · [`getStructureModel`](https://ngxviewbuilder.io/developers/api/structure#getstructuremodel) · [`setStructure`](https://ngxviewbuilder.io/developers/api/structure#setstructure) · [`updateStructure`](https://ngxviewbuilder.io/developers/api/structure#updatestructure) · [`notifyStructureChanged`](https://ngxviewbuilder.io/developers/api/structure#notifystructurechanged) · [`captureStructureSource`](https://ngxviewbuilder.io/developers/api/structure#capturestructuresource-clearcapturedstructuresource) · [`clearCapturedStructureSource`](https://ngxviewbuilder.io/developers/api/structure#capturestructuresource-clearcapturedstructuresource) |
| Settings | [`getSettings`](https://ngxviewbuilder.io/developers/api/structure#getsettings) · [`getSetting`](https://ngxviewbuilder.io/developers/api/structure#getsetting) · [`setSetting`](https://ngxviewbuilder.io/developers/api/structure#setsetting) · [`patchSettings`](https://ngxviewbuilder.io/developers/api/structure#patchsettings) · [`updateSettings`](https://ngxviewbuilder.io/developers/api/structure#updatesettings) · [`replaceSettings`](https://ngxviewbuilder.io/developers/api/structure#replacesettings) |
| Data | [`getData`](https://ngxviewbuilder.io/developers/api/data#getdata) · [`setData`](https://ngxviewbuilder.io/developers/api/data#setdata) · [`setElementsData`](https://ngxviewbuilder.io/developers/api/data#setelementsdata) · [`setValue`](https://ngxviewbuilder.io/developers/api/data#setvalue) · [`setElementValue`](https://ngxviewbuilder.io/developers/api/data#setelementvalue) · [`getElementValue`](https://ngxviewbuilder.io/developers/api/data#getelementvalue) · [`clearValue`](https://ngxviewbuilder.io/developers/api/data#clearvalue) · [`clearValues`](https://ngxviewbuilder.io/developers/api/data#clearvalues) · [`clearElementValue`](https://ngxviewbuilder.io/developers/api/data#clearelementvalue) · [`resetElementValue`](https://ngxviewbuilder.io/developers/api/data#resetelementvalue) · [`clearData`](https://ngxviewbuilder.io/developers/api/data#cleardata) · [`isDirty`](https://ngxviewbuilder.io/developers/api/data#isdirty) · [`markPristine`](https://ngxviewbuilder.io/developers/api/data#markpristine) · [`setElementErrors`](https://ngxviewbuilder.io/developers/api/data#setelementerrors) · [`clearElementErrors`](https://ngxviewbuilder.io/developers/api/data#clearelementerrors) · [`getElementErrors`](https://ngxviewbuilder.io/developers/api/data#getelementerrors) |
| Element lookup | [`getElement`](https://ngxviewbuilder.io/developers/api/elements#getelement) · [`getElementModel`](https://ngxviewbuilder.io/developers/api/elements#getelementmodel) · [`getElementLookup`](https://ngxviewbuilder.io/developers/api/elements#getelementlookup) · [`getElementByDataPath`](https://ngxviewbuilder.io/developers/api/elements#getelementbydatapath) · [`getElementBySchemaPath`](https://ngxviewbuilder.io/developers/api/elements#getelementbyschemapath) · [`getRenderedElements`](https://ngxviewbuilder.io/developers/api/elements#getrenderedelements) · [`getElementName` and friends](https://ngxviewbuilder.io/developers/api/elements#single-lookup-fields) · [`describeElement`](https://ngxviewbuilder.io/developers/api/elements#describeelement) |
| DOM | [`getElementDom`](https://ngxviewbuilder.io/developers/api/elements#getelementdom) · [`getElementDomById`](https://ngxviewbuilder.io/developers/api/elements#getelementdombyid) · [`getElementDomByTestId`](https://ngxviewbuilder.io/developers/api/elements#getelementdombytestid) · [`queryRenderDom`](https://ngxviewbuilder.io/developers/api/elements#queryrenderdom) · [`queryRenderDomAll`](https://ngxviewbuilder.io/developers/api/elements#queryrenderdomall) · [`getRenderRoot`](https://ngxviewbuilder.io/developers/api/elements#getrenderroot-registerrenderroot) · [`registerRenderRoot`](https://ngxviewbuilder.io/developers/api/elements#getrenderroot-registerrenderroot) |
| Properties | [`getElementProperty`](https://ngxviewbuilder.io/developers/api/elements#getelementproperty) · [`setElementProperty`](https://ngxviewbuilder.io/developers/api/elements#setelementproperty) · [`setElementProperties`](https://ngxviewbuilder.io/developers/api/elements#setelementproperties) · [`removeElementProperty`](https://ngxviewbuilder.io/developers/api/elements#removeelementproperty-removeelementproperties) · [`removeElementProperties`](https://ngxviewbuilder.io/developers/api/elements#removeelementproperty-removeelementproperties) · [`resetElementProperty`](https://ngxviewbuilder.io/developers/api/elements#resetelementproperty-resetelementproperties) · [`resetElementProperties`](https://ngxviewbuilder.io/developers/api/elements#resetelementproperty-resetelementproperties) · [`updateElement`](https://ngxviewbuilder.io/developers/api/elements#updateelement) · [`refreshElement`](https://ngxviewbuilder.io/developers/api/elements#refreshelement) |
| Element handle | [`element`](https://ngxviewbuilder.io/developers/api/elements#element-getelementapi) · [`getElementApi`](https://ngxviewbuilder.io/developers/api/elements#element-getelementapi) · [rows](https://ngxviewbuilder.io/developers/api/elements#rows-of-a-dynamic-table-or-panel) · [columns](https://ngxviewbuilder.io/developers/api/elements#columns-of-a-repeater) · [cells](https://ngxviewbuilder.io/developers/api/elements#cells) |
| Element defaults | [`setElementTypeDefault`](https://ngxviewbuilder.io/developers/api/elements#setelementtypedefault-setelementtypedefaults) · [`setElementTypeDefaults`](https://ngxviewbuilder.io/developers/api/elements#setelementtypedefault-setelementtypedefaults) · [`setElementDefaults`](https://ngxviewbuilder.io/developers/api/elements#setelementdefaults-defaults) · [`defaults`](https://ngxviewbuilder.io/developers/api/elements#setelementdefaults-defaults) · [`getElementDefaults`](https://ngxviewbuilder.io/developers/api/elements#getelementdefaults-clearelementdefaults) · [`clearElementDefaults`](https://ngxviewbuilder.io/developers/api/elements#getelementdefaults-clearelementdefaults) · [`getElementTypeBuiltInDefaults`](https://ngxviewbuilder.io/developers/api/elements#getelementtypebuiltindefaults) |
| Validation | [`validateData`](https://ngxviewbuilder.io/developers/api/validation#validatedata) · [`showToast`](https://ngxviewbuilder.io/developers/api/validation#showtoast) · [`notifyValidationResult`](https://ngxviewbuilder.io/developers/api/validation#notifyvalidationresult) · [`notifyComplete`](https://ngxviewbuilder.io/developers/api/validation#notifycomplete) · [`notifySaveRequested`](https://ngxviewbuilder.io/developers/api/validation#notifysaverequested) |
| Lifecycle | [render notifications](https://ngxviewbuilder.io/developers/api/validation#notifybeforerender-notifyrender-notifyafterrender) · [`notifyTabChanged`](https://ngxviewbuilder.io/developers/api/validation#notifytabchanged) · [`notifyCurrentPageChanged`](https://ngxviewbuilder.io/developers/api/validation#notifycurrentpagechanged) · [`notifyDialogClosed`](https://ngxviewbuilder.io/developers/api/validation#notifydialogclosed) · [element interaction notifications](https://ngxviewbuilder.io/developers/api/validation#element-interaction-notifications) |
| Data sources | [`reloadDataSource`](https://ngxviewbuilder.io/developers/api/data-sources#reloaddatasource) · [`reloadElementDataSource`](https://ngxviewbuilder.io/developers/api/data-sources#reloadelementdatasource) · [`reloadElementsByDataSource`](https://ngxviewbuilder.io/developers/api/data-sources#reloadelementsbydatasource) · [`setDefaultDataSources`](https://ngxviewbuilder.io/developers/api/data-sources#setdefaultdatasources) · [`setDataSourceTypeSettings`](https://ngxviewbuilder.io/developers/api/data-sources#setdatasourcetypesettings-getdatasourcetypesettings) · [`getDataSourceTypeSettings`](https://ngxviewbuilder.io/developers/api/data-sources#setdatasourcetypesettings-getdatasourcetypesettings) · [`setWebsocketAuthorizer`](https://ngxviewbuilder.io/developers/api/data-sources#setwebsocketauthorizer) |
| Variables | [`setRuntimeVariableContext`](https://ngxviewbuilder.io/developers/api/data-sources#setruntimevariablecontext) · [`getRuntimeVariableContext`](https://ngxviewbuilder.io/developers/api/data-sources#getruntimevariablecontext-clearruntimevariablecontext) · [`clearRuntimeVariableContext`](https://ngxviewbuilder.io/developers/api/data-sources#getruntimevariablecontext-clearruntimevariablecontext) · [`setRuntimeVariableDefinitions`](https://ngxviewbuilder.io/developers/api/data-sources#setruntimevariabledefinitions) · [`getRuntimeVariableDefinitions`](https://ngxviewbuilder.io/developers/api/data-sources#getruntimevariabledefinitions) · [`configureRuntimeVariables`](https://ngxviewbuilder.io/developers/api/data-sources#configureruntimevariables) |
| Language | [`getLanguage`](https://ngxviewbuilder.io/developers/api/language-theme#getlanguage-setlanguage) · [`setLanguage`](https://ngxviewbuilder.io/developers/api/language-theme#getlanguage-setlanguage) · [`resolveHostLanguage`](https://ngxviewbuilder.io/developers/api/language-theme#resolvehostlanguage-applyhostlanguage) · [`applyHostLanguage`](https://ngxviewbuilder.io/developers/api/language-theme#resolvehostlanguage-applyhostlanguage) · [`startLanguageSync`](https://ngxviewbuilder.io/developers/api/language-theme#startlanguagesync) · [`setApplicationLocale`](https://ngxviewbuilder.io/developers/api/language-theme#setapplicationlocale-getapplicationlocale) · [`getApplicationLocale`](https://ngxviewbuilder.io/developers/api/language-theme#setapplicationlocale-getapplicationlocale) · [`setLocale`](https://ngxviewbuilder.io/developers/api/language-theme#setlocale) · [`setContentTranslations`](https://ngxviewbuilder.io/developers/api/language-theme#setcontenttranslations) · [`setUiDictionaries`](https://ngxviewbuilder.io/developers/api/language-theme#setuidictionaries-setuitranslations) · [`setUiTranslations`](https://ngxviewbuilder.io/developers/api/language-theme#setuidictionaries-setuitranslations) · [`translateUi`](https://ngxviewbuilder.io/developers/api/language-theme#translateui) · [`setPropertyHints`](https://ngxviewbuilder.io/developers/api/language-theme#setpropertyhints-setpropertytypehints) · [`setPropertyTypeHints`](https://ngxviewbuilder.io/developers/api/language-theme#setpropertyhints-setpropertytypehints) |
| Theme | [`setThemeMode`](https://ngxviewbuilder.io/developers/api/language-theme#setthememode-getthememode) · [`getThemeMode`](https://ngxviewbuilder.io/developers/api/language-theme#setthememode-getthememode) · [`setTheme`](https://ngxviewbuilder.io/developers/api/language-theme#settheme) · [`setCustomTheme`](https://ngxviewbuilder.io/developers/api/language-theme#setcustomtheme-getcustomtheme) · [`getCustomTheme`](https://ngxviewbuilder.io/developers/api/language-theme#setcustomtheme-getcustomtheme) · [`setCssVariables`](https://ngxviewbuilder.io/developers/api/language-theme#setcssvariables-getcssvariables) · [`getCssVariables`](https://ngxviewbuilder.io/developers/api/language-theme#setcssvariables-getcssvariables) · [`setCustomCss`](https://ngxviewbuilder.io/developers/api/language-theme#setcustomcss-getcustomcss) · [`getCustomCss`](https://ngxviewbuilder.io/developers/api/language-theme#setcustomcss-getcustomcss) · [`setCustomCssUrls`](https://ngxviewbuilder.io/developers/api/language-theme#setcustomcssurls-getcustomcssurls) · [`getCustomCssUrls`](https://ngxviewbuilder.io/developers/api/language-theme#setcustomcssurls-getcustomcssurls) |
| Extensions | [`registerExtensions`](https://ngxviewbuilder.io/developers/api/extensions#registerextensions-registerextensionsasync) · [`registerExtensionsAsync`](https://ngxviewbuilder.io/developers/api/extensions#registerextensions-registerextensionsasync) · [expression functions](https://ngxviewbuilder.io/developers/api/extensions#registerexpressionfunction-registerexpressionfunctions) · [validator types](https://ngxviewbuilder.io/developers/api/extensions#registervalidatortype-registervalidatortypes) · [`getRegisteredValidatorTypes`](https://ngxviewbuilder.io/developers/api/extensions#getregisteredvalidatortypes-clearregisteredvalidatortypes) · [`clearRegisteredValidatorTypes`](https://ngxviewbuilder.io/developers/api/extensions#getregisteredvalidatortypes-clearregisteredvalidatortypes) · [custom elements](https://ngxviewbuilder.io/developers/api/extensions#registercustomelement-registercustomelements) · [`registerElementGroup`](https://ngxviewbuilder.io/developers/api/extensions#registerelementgroup) · [element properties](https://ngxviewbuilder.io/developers/api/extensions#element-properties) · [SVG icons](https://ngxviewbuilder.io/developers/api/extensions#svg-icons) · [table cell types](https://ngxviewbuilder.io/developers/api/extensions#table-cell-element-types) · [`getTableHeaderCenterExtensions`](https://ngxviewbuilder.io/developers/api/extensions#gettableheadercenterextensions) |
| Templates | [`getTemplates`](https://ngxviewbuilder.io/developers/api/builder#gettemplates) · [`loadTemplates`](https://ngxviewbuilder.io/developers/api/builder#loadtemplates-settemplates) · [`saveTemplate`](https://ngxviewbuilder.io/developers/api/builder#savetemplate-upserttemplate) · [`deleteTemplate`](https://ngxviewbuilder.io/developers/api/builder#deletetemplate-removetemplate) · [`setTemplateActionMap`](https://ngxviewbuilder.io/developers/api/builder#settemplateactionmap-registertemplateactiondatasource) · [`registerTemplateActionDataSource`](https://ngxviewbuilder.io/developers/api/builder#settemplateactionmap-registertemplateactiondatasource) |
| Element library | [`loadSidebarGroups`](https://ngxviewbuilder.io/developers/api/builder#loadsidebargroups) · [`saveSidebarGroup`](https://ngxviewbuilder.io/developers/api/builder#savesidebargroup-upsertsidebargroup) · [`deleteSidebarGroup`](https://ngxviewbuilder.io/developers/api/builder#deletesidebargroup-removesidebargroup) |
| Tables | [`setTableSettings`](https://ngxviewbuilder.io/developers/api/builder#settablesettings-gettablesettings) · [`getTableSettings`](https://ngxviewbuilder.io/developers/api/builder#settablesettings-gettablesettings) · [`setTableFilters`](https://ngxviewbuilder.io/developers/api/builder#settablefilters-gettablefilters) · [`getTableFilters`](https://ngxviewbuilder.io/developers/api/builder#settablefilters-gettablefilters) · [`setTableSavedFilters`](https://ngxviewbuilder.io/developers/api/builder#settablesavedfilters-gettablesavedfilters) · [`getTableSavedFilters`](https://ngxviewbuilder.io/developers/api/builder#settablesavedfilters-gettablesavedfilters) · [`request*` methods](https://ngxviewbuilder.io/developers/api/builder#asking-the-host-for-table-state) |
| Builder | [`switchToTab`](https://ngxviewbuilder.io/developers/api/builder#switchtotab-requesttabchange) · [`requestTabChange`](https://ngxviewbuilder.io/developers/api/builder#switchtotab-requesttabchange) · [`isBuilderAttached`](https://ngxviewbuilder.io/developers/api/builder#isbuilderattached-getbuilderadapter-attachbuilderadapter) · [`getBuilderAdapter`](https://ngxviewbuilder.io/developers/api/builder#isbuilderattached-getbuilderadapter-attachbuilderadapter) · [`attachBuilderAdapter`](https://ngxviewbuilder.io/developers/api/builder#isbuilderattached-getbuilderadapter-attachbuilderadapter) · [`setAiAssistantConfig`](https://ngxviewbuilder.io/developers/api/builder#setaiassistantconfig-getaiassistantconfig) · [`getAiAssistantConfig`](https://ngxviewbuilder.io/developers/api/builder#setaiassistantconfig-getaiassistantconfig) |