---
source: https://qlik.dev/apis/javascript/nebula-js/
last_updated: 2026-05-28T16:30:08+01:00
---
# nebula.js: stardust
`Version: 7.0.1` | _stable_
Product and framework agnostic integration API for Qlik's Associative Engine, commonly used with enigma.js. Consider using the qlik-embed toolkit for an easier embedding experience, whilst building on the same core technologies.
## Table of Contents
### Entries
- [embed](#embedapp-instanceconfig-function)
- [useState](#usestateinitialstate-function)
- [useEffect](#useeffecteffect-deps-function)
- [useMemo](#usememofactory-deps-function)
- [useRef](#userefinitialvalue-function)
- [usePromise](#usepromisefactory-deps-function)
- [useElement](#useelement-function)
- [useRect](#userect-function)
- [useLayout](#uselayout-function)
- [useStaleLayout](#usestalelayout-function)
- [useAppLayout](#useapplayout-function)
- [useModel](#usemodel-function)
- [useApp](#useapp-function)
- [useGlobal](#useglobal-function)
- [useSelections](#useselections-function)
- [useTheme](#usetheme-function)
- [useEmbed](#useembed-function)
- [useTranslator](#usetranslator-function)
- [useDeviceType](#usedevicetype-function)
- [useNavigation](#usenavigation-function-experimental)
- [usePlugins](#useplugins-function)
- [useAction](#useactionfactory-deps-function)
- [useConstraints](#useconstraints-function-deprecated)
- [useInteractionState](#useinteractionstate-function)
- [useOptions](#useoptions-function)
- [useImperativeHandle](#useimperativehandlefactory-deps-function)
- [onTakeSnapshot](#ontakesnapshotsnapshotcallback-function)
- [useRenderState](#userenderstate-function)
- [useEmitter](#useemitter-function)
- [useKeyboard](#usekeyboard-function)
- [Conversion](#conversion-namespace)
- [EnigmaMocker](#enigmamocker-namespace)
### Definitions
- [Translator](#translator-class)
- [Component](#component-interface)
- [LoadFallback](#loadfallbackundefined-function)
- [Configuration](#configuration-interface)
- [Context](#context-interface)
- [Galaxy](#galaxy-interface)
- [Embed](#embed-class)
- [Direction](#direction-union)
- [ListLayout](#listlayout-union)
- [FrequencyMode](#frequencymode-union)
- [SearchMode](#searchmode-union)
- [FieldEventTypes](#fieldeventtypes-union)
- [FieldInstance](#fieldinstance-class)
- [ThemeJSON](#themejson-alias)
- [ThemeInfo](#themeinfo-interface)
- [QInfo](#qinfo-interface)
- [Sheet](#sheet-class-experimental)
- [Viz](#viz-class)
- [ActionToolbarElement](#actiontoolbarelement-interface)
- [ActionElement](#actionelement-interface)
- [CellElement](#cellelement-interface)
- [CellBody](#cellbody-interface)
- [CellFooter](#cellfooter-interface)
- [CellTitle](#celltitle-interface)
- [CellSubTitle](#cellsubtitle-interface)
- [SheetElement](#sheetelement-interface-experimental)
- [VizElementAttributes](#vizelementattributes-interface)
- [VizElement](#vizelement-interface)
- [Flags](#flags-interface)
- [Plugin](#plugin-interface-experimental)
- [AppSelections](#appselections-class)
- [ObjectSelections](#objectselections-class)
- [Field](#field-union)
- [CreateConfig](#createconfig-interface)
- [RenderConfig](#renderconfig-interface)
- [LibraryField](#libraryfield-interface)
- [LoadType](#loadtype-interface)
- [TypeInfo](#typeinfo-interface)
- [RenderError](#rendererrormessage-originalerror-class)
- [Navigation](#navigation-class-experimental)
- [Visualization](#visualization-interface)
- [VisualizationDefinition](#visualizationdefinition-interface)
- [SetStateFn](#setstatefn-interface)
- [EffectCallback](#effectcallback-function)
- [Ref](#ref-interface)
- [Rect](#rect-interface)
- [ActionDefinition](#actiondefinition-interface)
- [Constraints](#constraints-interface-deprecated)
- [Interactions](#interactions-interface)
- [RenderState](#renderstate-interface)
- [Emitter](#emitter-class)
- [Keyboard](#keyboard-interface)
- [importProperties](#importpropertiesargs-function)
- [exportProperties](#exportpropertiesargs-function)
- [onPropertyChange](#onpropertychangeproperties-function)
- [QAEProperties](#qaeproperties-interface)
- [QAEDefinition](#qaedefinition-interface)
- [DataTarget](#datatarget-interface)
- [fieldTargetAddedCallback](#fieldtargetaddedcallbackfield-properties-function)
- [fieldTargetRemovedCallback](#fieldtargetremovedcallbackfield-properties-index-function)
- [FieldTarget](#fieldtarget-interface)
- [Theme](#theme-class)
- [move](#movearray-oldindex-newindex-function)
- [ExportFormat](#exportformat-interface)
- [ExportDataDef](#exportdatadef-interface)
- [ConversionType](#conversiontype-interface)
- [hyperCubeConversion](#hypercubeconversion-interface)
- [EnigmaMockerOptions](#enigmamockeroptions-interface-experimental)
- [ScalePalette](#scalepalette-interface)
- [DataPalette](#datapalette-interface)
- [ColorPickerPalette](#colorpickerpalette-interface)
- [DataColorSpecials](#datacolorspecials-interface)
## Entries
### embed(app, instanceConfig?) `function`
Initiates a new `Embed` instance using the specified enigma `app`.
#### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `app` | qix.Doc | Yes | - | |
| `instanceConfig` | [Configuration](#configuration-interface) | No | - | |
#### Returns
[Embed](#embed-class)
Examples
```javascript
import { embed } from '@nebula.js/stardust'
const n = embed(app);
n.render({ id: 'abc' });
```
---
#### createConfiguration(configuration) `function`
Creates a new `embed` scope bound to the specified `configuration`.
The configuration is merged with all previous scopes.
##### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `configuration` | [Configuration](#configuration-interface) | Yes | - | The configuration object |
##### Returns
[embed](#embedapp-instanceconfig-function)
Examples
```javascript
import { embed } from '@nebula.js/stardust';
// create a 'master' config which registers all types
const m = embed.createConfiguration({
types: [{
name: 'mekko',
version: '1.0.0',
load: () => Promise.resolve(mekko)
}],
});
// create an alternate config with dark theme
// and inherit the config from the previous
const d = m.createConfiguration({
context: {
theme: 'dark'
}
});
m(app).render({ type: 'mekko' }); // will render the object with default theme
d(app).render({ type: 'mekko' }); // will render the object with 'dark' theme
embed(app).render({ type: 'mekko' }); // will throw error since 'mekko' is not a register type on the default instance
```
---
### useState(initialState) `function`
Creates a stateful value.
#### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `initialState` | S \| function | Yes | - | The initial state. |
#### Returns
(S, [SetStateFn](#setstatefn-interface))[] - The value and a function to update it.
Examples
```javascript
import { useState } from '@nebula.js/stardust';
// ...
// initiate with simple primitive value
const [zoomed, setZoomed] = useState(false);
// update
setZoomed(true);
// lazy initiation
const [value, setValue] = useState(() => heavy());
```
---
### useEffect(effect, deps?) `function`
Triggers a callback function when a dependent value changes.
Omitting the dependency array will have the hook run on each update
and an empty dependency array runs only once.
#### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `effect` | [EffectCallback](#effectcallback-function) | Yes | - | The callback. |
| `deps` | any[] | No | - | The dependencies that should trigger the callback. |
Examples
```javascript
import { useEffect } from '@nebula.js/stardust';
// ...
useEffect(() => {
console.log('mounted');
return () => {
console.log('unmounted');
};
}, []);
useEffect(() => {
const clickHandler = () => { console.log('click') };
const button = element.querySelector('.button');
button.addEventListener('click', clickHandler);
return () => {
button.removeEventListener('click', clickHandler);
};
}, []);
```
---
### useMemo(factory, deps) `function`
Creates a stateful value when a dependent changes.
#### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `factory` | function | Yes | - | The factory function. |
| `deps` | any[] | Yes | - | The dependencies. |
#### Returns
`T` - The value returned from the factory function.
Examples
```javascript
import { useMemo } from '@nebula.js/stardust';
// ...
const v = useMemo(() => {
return doSomeHeavyCalculation();
}), []);
```
---
### useRef(initialValue) `function`
Creates a reference to a value not needed for rendering
While Nebula does not have a virtual DOM, it is still useful
to have a reference to an object that is retained across
renders and in it self does not trigger a render.
#### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `initialValue` | R | Yes | - | The initial value. |
#### Returns
[Ref](#ref-interface) - An object with the current value
Examples
```javascript
import { useRef } from '@nebula.js/stardust';
// ...
// initiate with simple value
const timesRendered = useRef(0);
useEffect(() => {
render(layout);
// increments the render counter, a useState would trigger another render
timesRendered.current += 1;
},[layout]);
```
---
### usePromise(factory, deps?) `function`
Runs a callback function when a dependent changes.
Useful for async operations that otherwise cause no side effects.
Do not add for example listeners withing the callback as there is no teardown function.
#### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `factory` | function | Yes | - | The factory function that calls the promise. |
| `deps` | any[] | No | - | The dependencies. |
#### Returns
`(P, Error)[]` - The resolved value or rejected error
Examples
```javascript
import { usePromise } from '@nebula.js/stardust';
import { useModel } from '@nebula.js/stardust';
// ...
const model = useModel();
const [resolved, rejected] = usePromise(() => model.getLayout(), [model]);
```
---
### useElement() `function`
Gets the HTMLElement this visualization is rendered into.
#### Returns
`HTMLElement`
Examples
```javascript
import { useElement } from '@nebula.js/stardust';
// ...
const el = useElement();
el.innerHTML = 'Hello!';
```
---
### useRect() `function`
Gets the size of the HTMLElement the visualization is rendered into.
#### Returns
[Rect](#rect-interface) - The size of the element.
Examples
```javascript
import { useRect } from '@nebula.js/stardust';
// ...
const rect = useRect();
useEffect(() => {
console.log('resize');
}, [rect.width, rect.height])
```
---
### useLayout() `function`
Gets the layout of the generic object associated with this visualization.
#### Returns
`qix.GenericObjectLayout`
Examples
```javascript
import { useLayout } from '@nebula.js/stardust';
// ...
const layout = useLayout();
console.log(layout);
```
---
### useStaleLayout() `function`
Gets the layout of the generic object associated with this visualization.
Unlike the regular layout, a _stale_ layout is not changed when a generic object enters
the modal state. This is mostly notable in that `qSelectionInfo.qInSelections` in the layout is
always `false`.
The returned value from `useStaleLayout()` and `useLayout()` are identical when the object
is not in a modal state.
#### Returns
`qix.GenericObjectLayout`
Examples
```javascript
import { useStaleLayout } from '@nebula.js/stardust';
// ...
const staleLayout = useStaleLayout();
console.log(staleLayout);
```
---
### useAppLayout() `function`
Gets the layout of the app associated with this visualization.
#### Returns
`qix.NxAppLayout` - The app layout
Examples
```javascript
import { useAppLayout } from '@nebula.js/stardust';
// ...
const appLayout = useAppLayout();
console.log(appLayout.qLocaleInfo);
```
---
### useModel() `function`
Gets the generic object API of the generic object connected to this visualization.
#### Returns
`qix.GenericObject | undefined`
Examples
```javascript
import { useModel } from '@nebula.js/stardust';
// ...
const model = useModel();
useEffect(() => {
model.getInfo().then(info => {
console.log(info);
})
}, []);
```
---
### useApp() `function`
Gets the doc API.
#### Returns
`qix.Doc | undefined` - The doc API.
Examples
```javascript
import { useApp } from '@nebula.js/stardust';
// ...
const app = useApp();
useEffect(() => {
app.getAllInfos().then(infos => {
console.log(infos);
})
}, []);
```
---
### useGlobal() `function`
Gets the global API.
#### Returns
`qix.Global | undefined` - The global API.
Examples
```javascript
import { useGlobal } from '@nebula.js/stardust';
// ...
const g = useGlobal();
useEffect(() => {
g.engineVersion().then(version => {
console.log(version);
})
}, []);
```
---
### useSelections() `function`
Gets the object selections.
#### Returns
[ObjectSelections](#objectselections-class) - The object selections.
Examples
```javascript
import { useSelections } from '@nebula.js/stardust';
import { useElement } from '@nebula.js/stardust';
import { useEffect } from '@nebula.js/stardust';
// ...
const selections = useSelections();
const element = useElement();
useEffect(() => {
const onClick = () => {
selections.begin('/qHyperCubeDef');
};
element.addEventListener('click', onClick);
return () => {
element.removeEventListener('click', onClick);
};
}, []);
```
---
### useTheme() `function`
Gets the theme.
#### Returns
[Theme](#theme-class) - The theme.
Examples
```javascript
import { useTheme } from '@nebula.js/stardust';
const theme = useTheme();
console.log(theme.getContrastingColorTo('#ff0000'));
```
---
### useEmbed() `function`
Available since: 1.7.0
Gets the embed instance used.
#### Returns
[Embed](#embed-class) - The embed instance used.
Examples
```javascript
import { useEmbed } from '@nebula.js/stardust';
const embed = useEmbed();
embed.render(...)
```
---
### useTranslator() `function`
Gets the translator.
#### Returns
[Translator](#translator-class) - The translator.
Examples
```javascript
import { useTranslator } from '@nebula.js/stardust';
// ...
const translator = useTranslator();
console.log(translator.get('SomeString'));
```
---
### useDeviceType() `function`
Gets the device type. ('touch' or 'desktop')
#### Returns
`string` - device type.
Examples
```javascript
import { useDeviceType } from '@nebula.js/stardust';
// ...
const deviceType = useDeviceType();
if (deviceType === 'touch') { ... };
```
---
### useNavigation() `function` **[experimental]**
Available since: 5.4.0
Gets the navigation api to control sheet navigation. When useNavigation is used in Sense, it returns Sense.navigation.
#### Returns
[Navigation](#navigation-class-experimental) - navigation api.
Examples
```javascript
import { useNavigation } from "@nebula.js/stardust";
// ...
const navigation = useNavigation();
const [activeSheetId, setActiveSheetId] = useState(navigation?.getCurrentSheetId() || "");
```
---
### usePlugins() `function`
Gets the array of plugins provided when rendering the visualization.
#### Returns
[Plugin](#plugin-interface-experimental)[] - array of plugins.
Examples
```javascript
// provide plugins that can be used when rendering
embed(app).render({
element,
type: 'my-chart',
plugins: [plugin]
});
```
```javascript
// It's up to the chart implementation to make use of plugins in any way
import { usePlugins } from '@nebula.js/stardust';
// ...
const plugins = usePlugins();
plugins.forEach((plugin) => {
// Invoke plugin
plugin.fn();
});
```
---
### useAction(factory, deps?) `function`
Registers a custom action.
#### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `factory` | function | Yes | - | |
| `deps` | any[] | No | - | |
#### Returns
`A`
Examples
```javascript
import { useAction } from '@nebula.js/stardust';
// ...
const [zoomed, setZoomed] = useState(false);
const act = useAction(() => ({
hidden: false,
disabled: zoomed,
action() {
setZoomed(prev => !prev);
},
icon: {}
}), [zoomed]);
```
---
### useConstraints() `function` _(deprecated)_
Gets the desired constraints that should be applied when rendering the visualization.
The constraints are set on the embed configuration before the visualization is rendered
and should be respected when implementing the visualization.
#### Returns
[Constraints](#constraints-interface-deprecated)
Examples
```javascript
// configure embed to disallow active interactions when rendering
embed(app, {
context: {
constraints: {
active: true, // do not allow interactions
}
}
}).render({ element, id: 'sdfsdf' });
```
```javascript
import { useConstraints } from '@nebula.js/stardust';
// ...
const constraints = useConstraints();
useEffect(() => {
if (constraints.active) {
// do not add any event listener if active constraint is set
return undefined;
}
const listener = () => {};
element.addEventListener('click', listener);
return () => {
element.removeEventListener('click', listener);
};
}, [constraints])
```
---
### useInteractionState() `function`
Gets the desired interaction states that should be applied when rendering the visualization.
The interactions are set on the embed configuration before the visualization is rendered
and should be respected when implementing the visualization.
#### Returns
[Interactions](#interactions-interface)
Examples
```javascript
// configure embed to disallow active interactions when rendering
embed(app, {
context: {
interactions: {
active: false, // do not allow interactions
}
}
}).render({ element, id: 'sdfsdf' });
```
```javascript
import { useInteractionState } from '@nebula.js/stardust';
// ...
const interactions = useInteractionState();
useEffect(() => {
if (!interactions.active) {
// do not add any event listener if active constraint is set
return undefined;
}
const listener = () => {};
element.addEventListener('click', listener);
return () => {
element.removeEventListener('click', listener);
};
}, [interactions])
```
---
### useOptions() `function`
Gets the options object provided when rendering the visualization.
This is an empty object by default but enables customization of the visualization through this object.
Options are different from setting properties on the generic object in that options
are only temporary settings applied to the visualization when rendered.
You have the responsibility to provide documentation of the options you support, if any.
#### Returns
`object`
Examples
```javascript
// when embedding the visualization, anything can be set in options
embed(app).render({
element,
type: 'my-chart',
options: {
showNavigation: true,
}
});
```
```javascript
// it is up to you use and implement the provided options
import { useOptions } from '@nebula.js/stardust';
import { useEffect } from '@nebula.js/stardust';
// ...
const options = useOptions();
useEffect(() => {
if (!options.showNavigation) {
// hide navigation
} else {
// show navigation
}
}, [options.showNavigation]);
```
---
### useImperativeHandle(factory, deps?) `function`
This is an empty object by default, but enables you to provide a custom API of your visualization to
make it possible to control after it has been rendered.
You can only use this hook once, calling it more than once is considered an error.
#### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `factory` | function | Yes | - | |
| `deps` | any[] | No | - | |
Examples
```javascript
import { useImperativeHandle } form '@nebula.js/stardust';
// ...
useImperativeHandle(() => ({
resetZoom() {
setZoomed(false);
}
}));
```
```javascript
// when embedding the visualization, you can get a handle to this API
// and use it to control the visualization
const ctl = await embed(app).render({
element,
type: 'my-chart',
});
ctl.getImperativeHandle().resetZoom();
```
---
### onTakeSnapshot(snapshotCallback) `function`
Registers a callback that is called when a snapshot is taken.
#### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `snapshotCallback` | function | Yes | - | |
Examples
```javascript
import { onTakeSnapshot } from '@nebula.js/stardust';
import { useState } from '@nebula.js/stardust';
import { useLayout } from '@nebula.js/stardust';
const layout = useLayout();
const [zoomed] = useState(layout.isZoomed || false);
onTakeSnapshot((copyOfLayout) => {
copyOfLayout.isZoomed = zoomed;
return Promise.resolve(copyOfLayout);
});
```
---
### useRenderState() `function`
Gets render state instance.
Used to update properties and get a new layout without triggering onInitialRender.
#### Returns
[RenderState](#renderstate-interface) - The render state.
Examples
```javascript
import { useRenderState } from '@nebula.js/stardust';
const renderState = useRenderState();
useState(() => {
if(needPropertiesUpdate(...)) {
useRenderState.pending();
updateProperties(...);
} else {
useRenderState.restore();
...
}
}, [...]);
```
---
### useEmitter() `function`
Gets an event emitter instance for the visualization.
#### Returns
[Emitter](#emitter-class)
Examples
```javascript
// In a Nebula visualization
import { useEmitter } from '@nebula.js/stardust';
useEffect(()=> {
// on some trigger
emitter.emit("trigger", params)
}, [...])
// In a mashup
const viz = await n.render({
element: el,
id: 'abcdef'
});
viz.addListener("trigger", ()=> {
// do something
})
```
---
### useKeyboard() `function`
Gets the desired keyboard settings and status to applied when rendering the visualization.
A visualization should in general only have tab stops if either `keyboard.enabled` is false or if active is true.
This means that either Nebula isn't configured to handle keyboard input or the chart is currently focused.
Enabling or disabling keyboardNavigation are set on the embed configuration and
should be respected by the visualization.
#### Returns
[Keyboard](#keyboard-interface)
Examples
```javascript
// configure nebula to enable navigation between charts
embed(app, {
context: {
keyboardNavigation: true, // tell Nebula to handle navigation
}
}).render({ element, id: 'sdfsdf' });
```
```javascript
import { useKeyboard } from '@nebula.js/stardust';
// ...
const keyboard = useKeyboard();
useEffect(() => {
// Set a tab stop on our button if in focus or if Nebulas navigation is disabled
button.setAttribute('tabIndex', keyboard.active || !keyboard.enabled ? 0 : -1);
// If navigation is enabled and focus has shifted, lets focus the button
keyboard.enabled && keyboard.active && button.focus();
}, [keyboard])
```
---
### Conversion `namespace`
Available since: 1.1.0
Provides conversion functionality to extensions.
#### Properties
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `hypercube` | [hyperCubeConversion](#hypercubeconversion-interface) | Yes | - | Provides conversion functionality to extensions with hyperCubes. |
Examples
```javascript
import { conversion } from '@nebula.js/stardust';
export default function() {
return {
qae: {
...
importProperties: ( exportFormat, initialProperties ) => conversion.hyperCube.importProperties(exportFormat, initialProperties),
exportProperties: ( fullPropertyTree ) => conversion.hyperCube.exportProperties(fullPropertyTree)
},
...
};
}
```
---
### EnigmaMocker `namespace`
Mocks Engima app functionality for demo and testing purposes.
---
#### fromGenericObjects(genericObjects, options?) `function` **[experimental]**
Available since: 3.0.0
Mocks Engima app functionality. It accepts one / many generic objects as input argument and returns the mocked Enigma app. Each generic object represents one visualisation and specifies how it behaves. For example, what layout to use the data to present.
The generic object is represented with a Javascript object with a number of properties. The name of the property correlates to the name in the Enigma model for `app.getObject(id)`. For example, the property `getLayout` in the generic object is used to define `app.getObject(id).getLayout()`. Any property can be added to the fixture (just make sure it exists and behaves as in the Enigma model!).
The value for each property is either fixed (string / boolean / number / object) or a function. Arguments are forwarded to the function to allow for greater flexibility. For example, this can be used to return different hypercube data when scrolling in the chart.
##### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `genericObjects` | object[] | Yes | - | Generic objects controlling behaviour of visualizations. |
| `options` | [EnigmaMockerOptions](#enigmamockeroptions-interface-experimental) | No | - | Options |
##### Returns
`Promise`
Examples
```javascript
const genericObject = {
getLayout() {
return {
qInfo: {
qId: 'qqj4zx',
qType: 'sn-grid-chart'
},
...
}
},
getHyperCubeData(path, page) {
return [ ... ];
}
};
const app = await EnigmaMocker.fromGenericObjects([genericObject]);
```
---
## Definitions
### Translator() `class`
---
#### language(lang?) `function`
Returns current locale.
##### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `lang` | string | No | - | language Locale to updated the currentLocale value |
##### Returns
`string` - current locale.
---
#### add(item) `function`
Registers a string in multiple locales
##### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `item` | object | Yes | - | |
Examples
```javascript
translator.add({
id: 'company.hello_user',
locale: {
'en-US': 'Hello {0}',
'sv-SE': 'Hej {0}'
}
});
translator.get('company.hello_user', ['John']); // Hello John
```
---
#### get(str, args?) `function`
Translates a string for current locale.
##### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `str` | string | Yes | - | ID of the registered string. |
| `args` | string[] | No | - | Values passed down for string interpolation. |
##### Returns
`string` - The translated string.
---
### Component `interface`
#### Properties
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `key` | string | Yes | - | The key of the component. Currently supporting components "theme" and "selections". |
Examples
```javascript
const n = embed(app);
const inst = await n.field('field_name');
inst.mount(document.querySelector('.listbox'), {
components: [{
key: 'theme',
header: {
fontColor: { color: '#f00' },
fontSize: 23,
},
content: {
fontSize: 16,
useContrastColor: false,
}
},{
key: 'selections',
colors: {
selected: { color: '#0f0' },
alternative: { color: '#ededed' },
excluded: { color: '#ccc' },
selectedExcluded: { color: '#bbb' },
possible: { color: '#fefefe' },
possible: { color: '#fefefe' },
}
}]
});
```
---
### LoadFallback(undefined) `function`
Fallback load function for missing types
#### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| | [LoadType](#loadtype-interface) | Yes | - | |
#### Returns
Promise<[Visualization](#visualization-interface)>
---
### Configuration `interface`
#### Properties
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `load` | [LoadFallback](#loadfallbackundefined-function) | No | - | Fallback load function for missing types |
| `context` | [Context](#context-interface) | No | - | Settings for the rendering instance |
| `types` | [TypeInfo](#typeinfo-interface)[] | No | - | Visualization types to register |
| `themes` | [ThemeInfo](#themeinfo-interface)[] | No | - | Themes to register |
| `hostConfig` | object | No | - | Qlik api compatible host config, see https://github.com/qlik-oss/qlik-api-ts/blob/main/docs/authentication.md#the-host-config |
| `anything` | object | No | - | |
Examples
```javascript
import { embed } from '@nebula.js/stardust'
n = embed(app, {
context: {
keyboardNavigation: true,
theme: 'purple',
},
load: ({ name, version }) => {
if (name === 'linechart') {
return Promise.resolve(line);
}
},
types: [
{
name: 'bar',
load: () => Promise.resolve(bar),
},
],
themes: [
{
id: 'purple',
load: () => Promise.resolve(purpleThemeJson),
},
],
});
```
---
### Context `interface`
#### Properties
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `theme` | string | No | "light" | |
| `language` | string | No | "en-US" | |
| `deviceType` | string | No | "auto" | |
| `constraints` | [Constraints](#constraints-interface-deprecated) | No | - | _(deprecated)_ |
| `interactions` | [Interactions](#interactions-interface) | No | - | |
| `keyboardNavigation` | boolean | No | false | |
| `disableCellPadding` | boolean | No | false | |
| `dataViewType` | string | No | "sn-table" | Type used for toggling to the data view (toggleDataView) This type need to be registered as well |
| `navigation` | [Navigation](#navigation-class-experimental) | No | - | |
---
### Galaxy `interface`
#### Properties
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `translator` | [Translator](#translator-class) | Yes | - | |
| `theme` | [Theme](#theme-class) | Yes | - | |
| `flags` | [Flags](#flags-interface) | Yes | - | |
| `deviceType` | string | Yes | - | |
| `hostConfig` | object | Yes | - | |
| `anything` | object | Yes | - | |
---
### Embed() `class`
---
#### render(cfg) `function`
Renders a visualization or sheet into an HTMLElement.
Visualizations can either be existing objects or created on the fly.
Support for sense sheets is experimental.
##### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `cfg` | [RenderConfig](#renderconfig-interface) | Yes | - | The render configuration. |
##### Returns
Promise<[Viz](#viz-class) | [Sheet](#sheet-class-experimental)> - A controller to the rendered visualization or sheet.
Examples
```javascript
// render from existing object
n.render({
element: el,
id: 'abcdef'
});
```
```javascript
// render on the fly
n.render({
element: el,
type: 'barchart',
fields: ['Product', { qLibraryId: 'u378hn', type: 'measure' }]
});
```
```javascript
// with AbortSignal
const controller = new AbortController();
n.render({
element: el,
type: 'barchart',
fields: ['Product', '=Sum(Sales)'],
signal: controller.signal
});
// Later: cancel the render
controller.abort();
```
---
#### create(cfg) `function`
Creates a visualization model
##### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `cfg` | [CreateConfig](#createconfig-interface) | Yes | - | The create configuration. |
##### Returns
`Promise` - An engima model
Examples
```javascript
// create a barchart in the app and return the model
const model = await n.create({
type: 'barchart',
fields: ['Product', { qLibraryId: 'u378hn', type: 'measure' }],
properties: { showTitle: true }
}
);
```
---
#### generateProperties(cfg) `function`
Generates properties for a visualization object
##### Parameters
| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `cfg` | [CreateConfig](#createconfig-interface) | Yes | - | The create configuration. |
##### Returns
`Promise