LogoLogo
GithubTwitterDiscordPlayground
English
English
  • 👋Atomico
  • 🚀Getting started with Atomico
  • ⚛️Getting started with Atomico for React users
  • 💡What can you do with Atomico?
    • You can create amazing webcomponents
    • You can create design systems
    • You can create websites
    • You can create mobile applications
    • You can create web applications
  • API
    • 🧬Props(Properties)
      • Value cycle as prop
      • Is it advisable to declare events using the props API?
    • 🧩VirtualDOM
      • Advanced
    • 🎣Hooks
      • useProp
      • useEvent
      • useRef
      • useHost
      • useState
      • useReducer
      • useEffect, useLayoutEffect and useInsertionEffect
      • useMemo and useCallback
      • useUpdate
      • useId
      • useContext
        • useProvider
      • usePromise
      • useAsync and useSuspense
      • useAbortController
    • 🔬Testing
      • Render cycle
      • atomico/test-hooks
      • atomico/test-dom
  • Guides
    • 🤔Frequent questions
      • Is it advisable to declare events using the props API?
      • How to declare events for your component at the type level for TSX?
      • When and why to use shadowDom?
      • Can I use Atomico in browsers without ESM support?
    • 🤩Component
      • Naming
      • CSS Styles with Shadow DOM
    • 🛡️Atomico with Typescript
      • Props
      • Component
      • Meta-types
        • Type
        • Event declaration
        • Method declaration
      • Check the correct use of hooks
    • 🤝Atomico and React
      • Integrating Atomico in React
      • From React to Atomico
        • Rendering Differences
        • VirtualDOM api differences
    • ⏳Atomico and Asynchrony
    • 🧠Atomico design patterns
      • ♻️Webcomponents with hybrid rendering
      • 🔗Slot as templates
      • 🔀Slot
    • 📖Atomico and Storybook
      • Frequent questions
    • 💧SSR / SSG
    • 🗃️Archives
      • Class inheritance
      • Forms and shadowDOM
      • Tips
      • Design systems
      • Atomico style guide
        • File structure
          • Monorepo
          • Design systems
  • packages
    • @atomico/hooks
      • useCurrentValue
      • use-intersection-observer
      • use-ref-values
      • use-script
      • use-attributes
      • use-prop-proxy
      • use-click-press
      • use-dollars
      • use-reflect-event
      • use-keyboar
      • use-click-coordinates
      • use-copy
      • use-debounce-state
      • use-form
      • use-listener
      • use-disabled
      • use-css
      • use-channel
      • use-promise
      • use-responsive-state
      • use-parent
      • use-resize-observer
      • use-slot
        • useSlot
        • useProxySlot
      • use-render
      • use-mutation-observer
      • use-css-light-dom
      • use-controller
      • use-router
      • use-async-effect
      • use-child-nodes
      • use-force-render
    • @atomico/store
      • Store
    • @atomico/storybook
    • @atomico/router
    • @atomico/vite
      • ⚙️Process CSS tag template blocks with PostCSS.
      • 🏗️Compile your code to be distributed optimally as a package.
      • 📕Use the JSX/TSX syntax of Atomico when using Storybook.
      • 🤖Automatically create customElements.define
      • ☑️Support for Vitest for Atomico.
      • 🧙‍♂️Server actions
    • @atomico/exports
      • 🚩CLI and Flags
      • 🤖Wrapper for React
    • @atomico/components
      • @atomico/keen-slider
      • @atomico/modal
      • @atomico/lottie
      • @atomico/table
    • @atomico/react
    • @atomico/postcss-tokens
      • Example with @atomico/vite
    • @atomico/wrapper
    • 🚫Deprecated
      • @atomico/magic-form
        • MagicFormProvider | <magic-form-provider>
        • MagicForm | <magic-form>
        • MagicForm Hooks
        • MagicForm in React and Preact
        • MagicForm in Microfrontend
        • MagicForm Patterns
      • @atomico/design-tokens
        • @atomico/design-tokens api
  • Support
    • Discord
    • Github
    • Twitter
Powered by GitBook
On this page
  • Syntax
  • Simple statements
  • Structured declaration
  • Prop.type
  • Prop.reflect
  • Prop.event
  • Prop.value
  • Reactivity in the scope of the webcomponent
  • Recommended articles

Was this helpful?

Edit on GitHub
Export as PDF
  1. API

Props(Properties)

The props in Atomico are the way to associate the webcomponent properties and reactive attributes that trigger the logic or interface of the webcomponent.

Props is the Atomico recommended way to declare visible and accessible states at the instance level of your webcomponents, with props you can:

  1. Access state via instance, example: document.querySelector("my-component").myStateProp.

  2. Dispatch events on prop value change, example: document.querySelector("my-component").addEventListener("myPropChange",console.log).

  3. Reflect attributes as prop, example: <my-component my-prop="...."> to document.querySelector("my-component").myProp.

  4. define strict input types for props.

Syntax

Any function that represents the webcomponent will be able to associate the static object props for the declaration of reactive properties and attributes, for example:

import { c } from "atomico";

function component() {
  return <host />;
}

component.props = {
  // Simple statement
  value1: String,
  // Structured statement
  value2: {
    type: String,
    reflect: true,
    attr: "advaceprop",
    value: "default string",
    event: {
      type: "UpdateAdvanceProp",
      bubbles: true,
    },
  },
};

customElement.define("web-component", c(component));

Consider that:

  1. The prop names in Camel Case format will be translated to for use as an attribute to the Kebab Case format, this behavior can be modified through the "attr" property when using a structured declaration.

  2. Structured declarations require the "type" property minimally.

  3. Not all types can use the "reflect" properties.

  4. The declaration of the "value" property can vary depending on the type.

Simple statements

Simple statements allow setting just type validations.

component.props = {
  propString: String,
  propNumber: Number,
  propObject: Object,
  propArray: Array,
  propBool: Boolean,
  propCallback: Function,
};

Structured declaration

Improve the definition by adding utility declarations, allowing for example to reflect the property's value as attributes, automatically emit events or associate default values. Remember these types of declarations minimally require the use of the type property.

Prop.type

// valid declaration
component.props = { myName: String };
// valid declaration
component.props = { myName: { type: String } };
Type
Supports reflect

String

✔️

Number

✔️

Boolean

✔️

Object

✔️

Array

✔️

Promise

❌

Symbol

❌

Function

❌

All references to existing types in the browser(HTMLElement, Element, Node, Date, File... more than 300 😎)

❌

Prop.reflect

If the "reflect" property is set to true, its value is reflected as an attribute of the webcomponent, this is useful for the declaration of CSS states, example:

component.props = {
  checked: {
    type: Boolean,
    reflect: true,
  },
};

Prop.event

It allows dispatching an automatic event before the prop value change, example:

component.props = {
  value: {
    type: String,
    event: {
      type: "change",
      bubbles: true,
      composed: true,
      detail: "any value",
      cancelable: true,
    },
  },
};
// listener
nodeComponent.addEventListener("change", handler);

Where:

  • event.type: String - optional, name of the event to be emitted when the prop is changed

  • event.bubbles: Boolean - optional, indicates that the event can be listened to by containers.

  • event.detail: Any - optional, allows to attach a custom detail for the event

  • event.cancelable: Boolean - optional, indicates that the event can be canceled by any listener

  • event.composed: Boolean - optional, allows the event to exceed the shadow-root limit

Prop.value

Atomico allows the definition of default values of the props.

WebComponents.props = {
  valueNormal: {
    type: Number,
    value: 100,
  },
  valueObject: {
    type: Object,
    value: () => ({}),
  },
};

The association of callback as value allows generating unique values for each instance of the webcomponent, this is useful with the Object and Array types since it eliminates the references between instances.

Reactivity in the scope of the webcomponent

Atomico removes the use of "this" given its functional approach, but adds the hook [useProp] (hooks / useprop.md) which allows to reference a prop for use with a functional syntax, eg:

function component() {
  const [message, setMessage] = useProp("message");
  return (
    <host>
      Hello, {message}
      <input oninput={({ target }) => setMessage(target.value)} />
    </host>
  );
}

component.props = { message: String };

Recommended articles

PreviousYou can create web applicationsNextValue cycle as prop

Last updated 1 year ago

Was this helpful?

The special properties of the event are the well-known Event Init, you can know more details in the .

🧬
attached documentation
Is it advisable to declare events using the props API?
Value cycle as prop