GitHub v1.3.1

refs System

Plugin

Complete guide to the core refs system for DOM element access in Coralite templates.

The refs system is a core Coralite feature that provides runtime DOM element access. It allows component scripts to safely access and manipulate DOM elements by their ref attributes. The framework handles automatic unique ID generation by assigning the generated ID to the ref attribute, leaving the standard id attribute intact.

Basic Usage

Here's the complete workflow for using refs:

html
Code copied!
  <template id="form-component">
    <form>
      <input type="text" ref="username" placeholder="Username">
      <input type="password" ref="password" placeholder="Password">
      <button type="button" ref="submitBtn">Submit</button>
    </form>
  </template>
  
  <script type="module">
    import { defineComponent } from 'coralite'
    
    export default defineComponent({
      client ({ signal, refs }) {
        const username = refs('username')
        const password = refs('password')
        const submitBtn = refs('submitBtn')
    
        submitBtn.addEventListener('click', () => {
          if (username.value && password.value) {
            console.log('Login:', username.value)
            // Handle form submission
          } else {
            alert('Please fill all fields')
          }
        }, { signal })
      }
    })
  </script>

Complete Examples

Interactive Counter

html
Code copied!
  <template id="counter">
    <div class="counter">
      <h2 ref="display">Count: {{ currentCount }}</h2>
      <button type="button" ref="increment">+</button>
      <button type="button" ref="decrement">-</button>
      <button type="button" ref="reset">Reset</button>
    </div>
  </template>
  
  <script type="module">
    import { defineComponent } from 'coralite'
    
    export default defineComponent({
      attributes: {
        initial: {
          type: Number,
          default: 0
        }
      },
      server ({ state }) {
        return {
          currentCount: state.initial
        }
      },
      client ({ state, signal, refs }) {
        const increment = refs('increment')
        const decrement = refs('decrement')
        const reset = refs('reset')
    
        increment.addEventListener('click', () => {
          state.currentCount++
        }, { signal })
    
        decrement.addEventListener('click', () => {
          state.currentCount--
        }, { signal })
    
        reset.addEventListener('click', () => {
          state.currentCount = state.initial
        }, { signal })
      }
    })
  </script>

Dynamic Form Validation

html
Code copied!
  <template id="signup-form">
    <form>
      <div>
        <input type="email" ref="email" placeholder="Email">
        <span ref="emailError" class="error"></span>
      </div>
      <div>
        <input type="password" ref="password" placeholder="Password">
        <span ref="passwordError" class="error"></span>
      </div>
      <button type="button" ref="submitBtn">Sign Up</button>
    </form>
  </template>
  
  <script type="module">
    import { defineComponent } from 'coralite'
    
    export default defineComponent({
      client ({ signal, refs }) {
        const email = refs('email')
        const password = refs('password')
        const emailError = refs('emailError')
        const passwordError = refs('passwordError')
        const submitBtn = refs('submitBtn')
    
        const validateEmail = (emailValue) => {
          return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(emailValue)
        }
    
        const validatePassword = (passwordValue) => {
          return passwordValue.length >= 8
        }
    
        submitBtn.addEventListener('click', () => {
          let valid = true
    
          // Validate email
          if (!validateEmail(email.value)) {
            emailError.textContent = 'Invalid email format'
            valid = false
          } else {
            emailError.textContent = ''
          }
    
          // Validate password
          if (!validatePassword(password.value)) {
            passwordError.textContent = 'Password must be 8+ characters'
            valid = false
          } else {
            passwordError.textContent = ''
          }
    
          if (valid) {
            console.log('Form submitted:', email.value)
            // Submit form
          }
        }, { signal })
      }
    })
  </script>

Tabbed Interface

html
Code copied!
  <template id="tabs">
    <div class="tabs">
      <div class="tab-buttons">
        <button type="button" ref="tab1">Tab 1</button>
        <button type="button" ref="tab2">Tab 2</button>
        <button type="button" ref="tab3">Tab 3</button>
      </div>
      <div class="tab-content">
        <div ref="content1">Content 1</div>
        <div ref="content2" hidden>Content 2</div>
        <div ref="content3" hidden>Content 3</div>
      </div>
    </div>
  </template>
  
  <script type="module">
    import { defineComponent } from 'coralite'
    
    export default defineComponent({
      client ({ signal, refs }) {
        const buttons = [refs('tab1'), refs('tab2'), refs('tab3')]
        const contents = [refs('content1'), refs('content2'), refs('content3')]
    
        buttons.forEach((btn, index) => {
          btn.addEventListener('click', () => {
            // Hide all contents
            contents.forEach(content => {
              content.hidden = true
            })
    
            // Show selected content
            contents[index].hidden = false
    
            // Update button states
            buttons.forEach(b => b.classList.remove('active'))
            btn.classList.add('active')
          }, { signal })
        })
      }
    })
  </script>

Key Points

  • Runtime Access: refs('refName') gets DOM elements
  • Automatic Caching: Elements cached after first access
  • Safe Queries: Returns null if element not found
  • Under the Hood: Framework assigns the generated unique ID to the ref attribute and queries it via document.querySelector('[ref="..."]'). E2E tests should query this compiled ref attribute directly (e.g., [ref="my-component__btn-0"]).