Getting Started: Your First Component

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>).



<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.




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

  

  <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 Tokens. Tokens allow us to pass data into our component using double curly braces ({{ }}).



<template id="my-counter">
  <div class="counter-box">
    

    <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({
    tokens: {
      // Define our initial value
      currentCount: () => 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 plugin 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.script function inside defineComponent. This script is what runs in the user's browser.



<template id="my-counter">
  <div class="counter-box">
    

    <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({
    tokens: {
      currentCount: () => 0
    },
    client: {
      // The script function runs in the browser!
      script: ({ values, helpers }) => {
        // 1. Get our elements using the refs helper
        const display = helpers.refs('countDisplay')
        const btn = helpers.refs('incrementBtn')
  
        // 2. Set up our state
        let count = values.currentCount
  
        // 3. Add an event listener
        btn.addEventListener('click', () => {
          count++
          display.textContent = count
        })
      }
    }
  })
</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 tokens ({{ }}).
Add interactivity using client.script and the refs plugin.

Ready to learn more? Dive into the Core Concepts to master Static Components and Dynamic Components.