Components

Components are the fundamental building blocks of Quantum applications. They encapsulate logic, data processing, and output generation in reusable, modular units.

Basic Structure

Every Quantum component follows this structure:

<q:component name="ComponentName" xmlns:q="https://quantum.lang/ns">
  <!-- Component logic here -->
  <q:return value="output" />
</q:component>

Required Elements

Element	Description
q:component	Root element
name attribute	Unique identifier (PascalCase)
xmlns:q	Quantum namespace declaration

Simple Components

Hello World

<q:component name="HelloWorld" xmlns:q="https://quantum.lang/ns">
  <q:return value="Hello, World!" />
</q:component>

Output: "Hello, World!"

Multiple Returns

<q:component name="Colors" xmlns:q="https://quantum.lang/ns">
  <q:return value="Red" />
  <q:return value="Green" />
  <q:return value="Blue" />
</q:component>

Output: ["Red", "Green", "Blue"]

Component Parameters

Accept input with q:param:

<q:component name="Greeting" xmlns:q="https://quantum.lang/ns">
  <q:param name="name" type="string" required="true" />
  <q:param name="formal" type="boolean" default="false" />

  <q:if condition="formal">
    <q:return value="Good day, {name}." />
  </q:if>
  <q:else>
    <q:return value="Hey {name}!" />
  </q:else>
</q:component>

Parameter Attributes

Attribute	Description	Example
name	Parameter name	name="userId"
type	Data type	type="string"
required	Required parameter	required="true"
default	Default value	default="10"

Supported Types

• string - Text values
• number - Integers and decimals
• boolean - true/false
• array - JSON arrays
• object - JSON objects
• email - Valid email format
• date - Date strings

Component State

Use q:set for internal variables:

<q:component name="Counter" xmlns:q="https://quantum.lang/ns">
  <q:set name="count" value="0" type="number" />
  <q:set name="step" value="1" type="number" />

  <q:function name="increment">
    <q:set name="count" value="{count + step}" />
  </q:function>

  <q:return value="Count: {count}" />
</q:component>

Variable Validation

<q:set name="email"
       value="user@example.com"
       validate="email" />

<q:set name="age"
       type="number"
       value="25"
       range="0..150" />

<q:set name="status"
       type="string"
       value="active"
       enum="active,inactive,pending" />

Component Functions

Define reusable logic with q:function:

<q:component name="Calculator" xmlns:q="https://quantum.lang/ns">
  <q:function name="add" returnType="number">
    <q:param name="a" type="number" required="true" />
    <q:param name="b" type="number" required="true" />
    <q:set name="result" value="{a + b}" />
    <q:return value="{result}" />
  </q:function>

  <q:function name="multiply" returnType="number">
    <q:param name="a" type="number" required="true" />
    <q:param name="b" type="number" required="true" />
    <q:return value="{a * b}" />
  </q:function>

  <!-- Use the functions -->
  <q:set name="sum" value="{add(5, 3)}" />
  <q:set name="product" value="{multiply(4, 7)}" />

  <q:return value="5 + 3 = {sum}" />
  <q:return value="4 * 7 = {product}" />
</q:component>

Loops in Components

Range Loop

<q:component name="Numbers" xmlns:q="https://quantum.lang/ns">
  <q:loop type="range" var="i" from="1" to="5">
    <q:return value="Number {i}" />
  </q:loop>
</q:component>

Output: ["Number 1", "Number 2", "Number 3", "Number 4", "Number 5"]

Array Loop

<q:component name="Fruits" xmlns:q="https://quantum.lang/ns">
  <q:set name="fruits" value='["Apple", "Banana", "Cherry"]' />

  <q:loop type="array" var="fruit" items="{fruits}">
    <q:return value="I like {fruit}" />
  </q:loop>
</q:component>

List Loop

<q:component name="Colors" xmlns:q="https://quantum.lang/ns">
  <q:loop type="list" var="color" items="red,green,blue" delimiter=",">
    <q:return value="Color: {color}" />
  </q:loop>
</q:component>

Loop with Index

<q:component name="IndexedList" xmlns:q="https://quantum.lang/ns">
  <q:set name="items" value='["First", "Second", "Third"]' />

  <q:loop type="array" var="item" items="{items}" index="i">
    <q:return value="{i + 1}. {item}" />
  </q:loop>
</q:component>

Output: ["1. First", "2. Second", "3. Third"]

Conditionals

Basic If/Else

<q:component name="AgeCheck" xmlns:q="https://quantum.lang/ns">
  <q:param name="age" type="number" required="true" />

  <q:if condition="age >= 18">
    <q:return value="Adult" />
  </q:if>
  <q:else>
    <q:return value="Minor" />
  </q:else>
</q:component>

Multiple Conditions

<q:component name="Grade" xmlns:q="https://quantum.lang/ns">
  <q:param name="score" type="number" required="true" />

  <q:if condition="score >= 90">
    <q:return value="A" />
  </q:if>
  <q:elseif condition="score >= 80">
    <q:return value="B" />
  </q:elseif>
  <q:elseif condition="score >= 70">
    <q:return value="C" />
  </q:elseif>
  <q:elseif condition="score >= 60">
    <q:return value="D" />
  </q:elseif>
  <q:else>
    <q:return value="F" />
  </q:else>
</q:component>

Data Binding

Use {expression} for dynamic values:

Simple Variables

<q:set name="name" value="Alice" />
<q:return value="Hello, {name}!" />

Output: "Hello, Alice!"

Object Properties

<q:set name="user" type="object" value='{"name": "Bob", "age": 30}' />
<q:return value="{user.name} is {user.age} years old" />

Output: "Bob is 30 years old"

Expressions

<q:set name="price" value="100" />
<q:set name="quantity" value="5" />
<q:return value="Total: ${price * quantity}" />

Output: "Total: $500"

String Functions

Functions are called with the value as an argument — see the function list:

<q:set name="text" value="hello world" />
<q:return value="{upper(text)}" />

Output: "HELLO WORLD"

Nested Components

Components can contain nested structures:

<q:component name="Report" xmlns:q="https://quantum.lang/ns">
  <q:set name="categories" value='[
    {"name": "Electronics", "items": ["Phone", "Laptop"]},
    {"name": "Clothing", "items": ["Shirt", "Pants"]}
  ]' />

  <q:loop type="array" var="category" items="{categories}">
    <q:return value="Category: {category.name}" />

    <q:loop type="array" var="item" items="{category.items}">
      <q:return value="  - {item}" />
    </q:loop>
  </q:loop>
</q:component>

Using one component inside another

A page uses another component — a card, a layout — by importing it and writing it as a tag. Save as components/_parts/Card.q:

<q:component name="Card" xmlns:q="https://quantum.lang/ns">
  <q:param name="title" required="true" />
  <section class="card">
    <h2>{title}</h2>
    <q:slot />
  </section>
</q:component>

Save as components/index.q:

<q:component name="Home" xmlns:q="https://quantum.lang/ns">
  <q:import component="Card" from="_parts" />
  <q:set name="open" value="3" type="number" />

  <Card title="Open tickets: {open}">
    <p>The oldest is from {'Monday'}.</p>
  </Card>
</q:component>

Opening / shows the card with the title Open tickets: 3 and, inside it, The oldest is from Monday.

• q:import looks the component up in paths.components of quantum.config.yaml, in the from folder when declared. A folder whose name starts with _ is not served as pages, which suits parts like this one.
• Each attribute of the tag is a q:param of the component, evaluated in the page: title="Open tickets: {open}" sees the page's open. A missing required param is an error.
• What is between <Card> and </Card> is drawn in the page's scope and goes where the component has <q:slot />.
• The component uses the page's datasources and services and sees the same session, application and request.
• A component that is not found, or that fails, is an error of the page — never a section that silently disappears.

Error Handling

Validation Errors

<!-- Missing required parameter -->
<q:component name="BadComponent" xmlns:q="https://quantum.lang/ns">
  <q:param name="id" required="true" />
  <!-- Error: 'id' is required but not provided -->
</q:component>

Runtime Errors

<q:component name="ErrorExample" xmlns:q="https://quantum.lang/ns">
  <q:return value="{undefined_variable}" />
  <!-- Error: undefined_variable is not defined -->
</q:component>

Error Messages

Quantum provides descriptive error messages:

[ERROR] Component 'MyComponent' at line 5:
  Variable 'userName' is not defined in this scope.
  Did you mean 'username'?

Best Practices

1. Single Responsibility

Each component should have one clear purpose:

<!-- Good: Focused component -->
<q:component name="UserEmail" xmlns:q="https://quantum.lang/ns">
  <q:param name="email" type="email" required="true" />
  <q:return value="{email}" />
</q:component>

2. Use Descriptive Names

Prefer <q:component name="ProductPriceFormatter"> to <q:component name="PF">: the name is what a page that uses it reads.

3. Document Parameters

<!--
  Formats a price with currency symbol.

  @param amount - The price amount (required)
  @param currency - Currency code (default: USD)
-->
<q:component name="PriceFormatter" xmlns:q="https://quantum.lang/ns">
  <q:param name="amount" type="number" required="true" />
  <q:param name="currency" type="string" default="USD" />
  ...
</q:component>

4. Validate Input

<q:component name="SafeComponent" xmlns:q="https://quantum.lang/ns">
  <q:param name="count" type="number" required="true" />

  <q:if condition="count < 0">
    <q:return value="Error: count must be positive" />
  </q:if>

  <q:loop type="range" var="i" from="1" to="{count}">
    <q:return value="Item {i}" />
  </q:loop>
</q:component>

Next Steps

• State Management - Advanced variable handling
• Functions - Creating reusable logic
• Loops - Iteration patterns
• Conditionals - Control flow