Props System

Master the flow of data between components. PawaJS uses a unique getter-based prop system to ensure fine-grained reactivity.

The Getter Pattern

Unlike many frameworks that pass raw values, PawaJS passes props as functions (getters). This is the secret to its "Continuity" model—by passing a function, the child component can execute it at any time to retrieve the latest reactive value without requiring the whole component to re-render.

Important: Always call your props as functions in your template or logic, e.g., propName(). The only exception is the children prop, which is a raw string.

Prop Naming & Conversions

PawaJS automatically normalizes attribute names to JavaScript-friendly prop names. This ensures consistency with standard DOM property naming conventions.

CamelCase Conversion
Hyphenated attributes are converted to camelCase.
  • :on-change-value → onChangeValue
  • :user-id → userId
  • :is-loading → isLoading
Special Mappings
Reserved HTML attributes are mapped to properties.
  • class → className
  • default → defaultValue
  • for → htmlFor

Reactive vs. Static Props

Reactive Binding (:prop)

Use a colon prefix to pass reactive state, numbers, or complex JS expressions.

html 

                 
<user-profile 
  :age="25" 
  :name="user.name.value" 
/>

Since it evaluates as JavaScript, you can also define inline functions:

html 

                 
<custom-list 
  :on-item-click="(id) => console.log('Item selected:', id)" 
/>

Static Binding (prop)

Omit the colon to pass fixed strings. These are still received as getters returning that string.

html 

                 
<user-profile 
  theme="dark" 
  label="Account" 
/>

Event Handlers: Directive vs. Prop

Understanding how PawaJS handles event handlers is crucial for correct component interaction.

on-click="myFunction()" (Event Directive)

This attaches a native DOM event listener directly to the custom element. The expression myFunction() is executed in the parent component's context when the event fires. This is the standard way to handle events on any element, including custom elements, if the event is to be handled by the parent.

:on-click="myFunction" (Function Prop)

This passes the myFunction reference as a prop (named onClick) to the child component. The child component must explicitly declare and use this prop in its function signature.

Key Distinction: If a child component does not declare an onClick prop, then an attribute like :on-click="myFunction" will be received by the component but effectively ignored if not explicitly consumed. If you intend for an event to be handled by the custom element itself, and potentially "fall through" to a native DOM event listener if the child component doesn't explicitly consume it as a prop, you should use the on- directive without the colon (e.g., on-click="myFunction()"). This ensures the event is always attached as a native DOM event listener.

Attribute Fallthrough (--)

When you pass standard HTML attributes like class, style, or id to a component, they are captured as "rest props". You can direct these attributes to a specific element inside your component using the double-dash -- syntax.

Implementation
html 

                 
<!-- Parent Template -->
<custom-button class="btn-primary" id="login-btn">
  Login
</custom-button>
js 

                 
// Component Definition
const CustomButton = ({ children }) => {
  return html`
    <div class="wrapper">
       <!-- Attributes from parent will land on this button -->
       <button -->${children}</button>
    </div>`;
};

The forwardProps Hook

If you need to programmatically manage which props are considered "rest attributes" or if you want to forward them to another PawaJS component instead of a native DOM element, use the forwardProps hook.

js 

                 
import { forwardProps, html } from 'pawajs';

const InputGroup = ({children,...props}) => {
  // Explicitly forward the incoming props to the next level
  forwardProps(props);

  return html`
    <div class="group">
      <label>User Input</label>
      <!-- 'props' are now available for the next component's fallthrough -->
      <custom-input --></custom-input>
    </div>`;
};

Type Safety & Validation

PawaJS includes a runtime validation utility to ensure your components receive the data they expect.

js 

                 
import { useValidateComponent } from 'pawajs';

const MyComponent = ({ title }) => { ... };

useValidateComponent(MyComponent, {
  title: {
    type: String,
    strict: true, // Required prop
    default: 'Default Title'
  },
  count: {
    type: Number,
    err: 'The count prop must be a valid integer'
  }
});