npm package: @servicenow/ui-core
Description: Core package of the UI Framework on Next Experience
Latest version: 24.1.1

# @servicenow/ui-core

<a name="createCustomElement
Define a custom element.module_"></a>

## createCustomElement
Define a custom element.

| Param | Type | Description |
| --- | --- | --- |
| elementName | <code>string</code> | The tag name of the custom element. |
| config | <code>Object</code> | The custom element configuration. |
| [config.initialState] | <code>Object</code> | The initial state for a component. |
| [config.properties] | <code>Object</code> | The properties used by a custom element. |
| config.properties.name | <code>Object</code> | The name of the property. |
| [config.properties.name.default] | <code>\*</code> | The default value of the property. |
| [config.properties.name.computed] | <code>function</code> | A function that computes the property value. |
| config.properties.name.computed.state | <code>Object</code> | The custom element state. |
| [config.properties.name.onChange] | <code>function</code> | A function that will be called with the new property value, the previous value, and the `dispatch` function. |
| [config.properties.name.reflect] | <code>boolean</code> | Reflect property change to corresponding attribute. |
| [config.properties.name.unstableParse] | <code>boolean</code> | Parse attribute values when corresponding properties are set. |
| [config.properties.name.readOnly] | <code>boolean</code> | Property cannot be externally set. |
| [config.actions] | <code>Object</code> | The actions the custom element dispatches. |
| config.actions.type | <code>Object</code> | The action type, name. |
| [config.actions.private] | <code>boolean</code> | Indicates if the action is visible outside of the custom element. |
| [config.actions.handlers] | <code>Array</code> | Effect handlers to run when the action type is dispatched. |
| config.renderer | <code>Object</code> | The renderer to be used by the custom element. |
| config.renderer.type | <code>function</code> | The library that renders the view. |
| config.renderer.view | <code>function</code> | A function that is executed by onStateChange. |
| [config.renderer.transformState] | <code>function</code> | A function that executes before a component's state is passed to the handler. |
| [config.onDisconnect] | <code>function</code> | A function that executes when the custom element is disconnected. |
| [config.onConnect] | <code>function</code> | A function that executes when the custom element is connected. |
| [config.behaviors] | <code>Array</code> | Behaviors to applied to the custom element. |

**Example**
```js
import {createCustomElement} from '@servicenow/ui-core';
import snabbdom from '@servicenow/ui-renderer-snabbdom';

createCustomElement('sn-hello-world', {
  properties: {
    name: {
      default: 'Fred'
    }
  },
  renderer: {
    type: snabbdom,
    transformState({properties}) { return properties; },
    view: ({name}) => { return <p>Hello {name}!</p>; }
  }
});
```

## Action Routing
Actions will "bubble" up the component hierarchy unless they are explictly stopped by `dispatch` meta data, `{stopPropagtion: true}`, or part of the `stopPropagtion` configuration for a component definition.

```javascript
dispatch('SOMETHING_HAPPENED', {somethingHappened: true}, {stopPropagtion: true});
```

_OR_

```javascript
createCustomElement('sn-foo', () => null, {
  stopPropagtion: ['SOMETHING_HAPPENED']
});
 ```