Getting Started

Welcome to Coralite! This tutorial will walk you through building your very first interactive web component using Coralite's unique HTML-first approach. We'll start with a simple static template and slowly make it dynamic.

1. The Setup #

First, make sure you have a basic Coralite project structure. If you used the create-coralite CLI (from the Quick Start guide), you're already good to go. Otherwise, create the following folders:

  my-coralite-site/
  ├── src/
  │   ├── components/
  │   └── pages/
  └── package.json

2. Creating a Static Component #

In Coralite, components are just standard HTML <template> tags. Let's create a simple counter component. Create a file named counter.html inside your src/components/ directory.

Give the template an id attribute. This ID becomes the custom HTML tag you will use in your pages (e.g., <my-counter>).

<!-- src/components/counter.html -->
<template id="my-counter">
  <div class="counter-box">
    <h2>Count: <span>0</span></h2>
    <button type="button">Increment</button>
  </div>
</template>

3. Using the Component in a Page #

Now, let's use this static component. Create an index.html file inside your src/pages/ directory. You can use your component simply by writing its tag name.

<!-- src/pages/index.html -->

<html lang="en">
<head>
  <title>My First Coralite App</title>
</head>
<body>
  <h1 class="display">Welcome!</h1>

  <!-- Use our new component -->
  <my-counter></my-counter>

</body>
</html>

If you run your build command (npm run build), Coralite will generate an HTML page where the <my-counter> tag is replaced by the contents of your template.

4. Making It Dynamic with defineComponent #

Right now, our counter is just static HTML. Clicking the button does nothing. To add interactivity and data processing, we need to turn this into a Dynamic Component.

To do this, we add a <script type="module"> tag below our template and export the defineComponent function.

Let's update our counter.html to define an initial count value using Attributes. Attributes allow us to pass data into our component using double curly braces ({{ }}).

<!-- src/components/counter.html -->
<template id="my-counter">
  <div class="counter-box">
    <!-- We replace the hardcoded 0 with our state key -->
    <h2>Count: <span class="count-display">{{ currentCount }}</span></h2>
    <button type="button" class="btn">Increment</button>
  </div>
</template>

<script type="module">  
  import { defineComponent } from 'coralite'
  
  export default defineComponent({
    attributes: {
      // Define our initial value via an attribute
      currentCount: {
        type: Number,
        default: 0
      }
    }
  })
</script>

5. Adding Interactivity with Refs #

We have data, but we still need the button to actually do something! Coralite provides a built-in refs system to easily target DOM elements without needing to use document.querySelector.

First, add a ref attribute to the elements we want to interact with in our template.

Second, add a client function inside defineComponent. This script is what runs in the user's browser.

<!-- src/components/counter.html -->
<template id="my-counter">
  <div class="counter-box">
    <!-- Add ref attributes -->
    <h2>Count: <span ref="countDisplay">{{ currentCount }}</span></h2>
    <button type="button" ref="incrementBtn">Increment</button>
  </div>
</template>

<script type="module">  
  import { defineComponent } from 'coralite'
  
  export default defineComponent({
    attributes: {
      currentCount: {
        type: Number,
        default: 0
      }
    },
    // The client function runs in the browser!
    client: ({ state, signal, refs }) => {
      const btn = refs('incrementBtn')
  
      // Add an event listener using the provided signal for cleanup
      btn.addEventListener('click', () => {
        // Mutating state automatically updates the UI!
        state.currentCount++
      }, { signal })
    }
  })
</script>

Congratulations! #

You have just built your first fully functional, interactive Coralite component! You learned how to:

Create a static HTML template component.
Use the component in a page.
Turn it into a dynamic component using defineComponent.
Bind data using state and attributes.
Add interactivity using client, state, and the refs system.

Ready to learn more? Dive into the Core Concepts to master Coralite's philosophy.