qariyb-event-list

Displays a collection of events from an organization in a grid or list layout. Internally uses <qariyb-event-card> components.

<qariyb-event-list organization-id="01HWORG123ABC456"></qariyb-event-list>

Features

Grid or list layout
Configurable event limit
Optional past events display
Skeleton loading states
Responsive grid
"Powered by Qariyb" footer (optional)

Attributes

Required

Name
organization-id
Type
string
Description
The organization ULID from your Qariyb dashboard.

Optional

Name
limit
Type
string
Description
Maximum events to display, 1–50. Defaults to '10'. Values above 50 are clamped by the API.
Name
offset
Type
string
Description
Zero-based offset into the organization's event list, for paging. Defaults to '0'. Combine with limit to page: offset="10" limit="10" is page 2.
Name
layout
Type
'grid' | 'list'
Description
Display layout. Defaults to 'grid'.
Name
show-past
Type
'true' | 'false'
Description
Include past events. Defaults to 'false'.
Name
theme
Type
'light' | 'dark' | 'flat' | 'minimal'
Description
Theme preset. Defaults to 'light'.
Name
accent-color
Type
string
Description
Primary color in hex format. Defaults to '#10b981'.

Callback Attributes

Name
on-ready
Type
function
Description
Called when component mounts. Receives { organizationId }.
Name
on-loaded
Type
function
Description
Called when events load. Receives { events, total, hasMore }.
Name
on-error
Type
function
Description
Called on error. Receives { error, organizationId }.

Events

qariyb:list:ready

Emitted when component mounts.

interface ListReadyDetail {
  organizationId: string;
}

qariyb:list:loaded

Emitted when events are fetched.

interface ListLoadedDetail {
  events: QariybEvent[];
  total: number;
  hasMore: boolean;
}

The API returns paging metadata in the X-Total-Count, X-Offset and X-Limit response headers rather than in the body. A cross-origin widget can only read those if the API lists them in Access-Control-Expose-Headers; when it cannot, the component falls back to offset + events.length for total and reports hasMore: false. Treat hasMore: false as "no more known", not as a guarantee that the list is complete.

list.addEventListener('qariyb:list:loaded', (e) => {
  const { events, total, hasMore } = e.detail.data;

  console.log(`Loaded ${events.length} of ${total} events`);
  console.log('Events:', events.map(e => e.title));

  if (hasMore) {
    console.log('More events available');
  }
});

qariyb:list:error

Emitted when an error occurs.

interface ListErrorDetail {
  error: string;
  organizationId: string;
}

Public Methods

getEvents()

Returns the loaded events array.

getEvents(): QariybEvent[]

const list = document.querySelector('qariyb-event-list');
const events = list.getEvents();

events.forEach(event => {
  console.log(`${event.title} - ${event.start_date}`);
});

refresh()

Refetch events from the API.

refresh(): void

const list = document.querySelector('qariyb-event-list');
list.refresh();

Layout Options

Grid Layout (Default)

Events display in a responsive grid:

<qariyb-event-list
  organization-id="01HWORG..."
  layout="grid"
></qariyb-event-list>

Grid behavior:

Columns auto-fill based on container width
Minimum card width: 300px
Gap: 24px

List Layout

Events stack vertically:

<qariyb-event-list
  organization-id="01HWORG..."
  layout="list"
></qariyb-event-list>

List behavior:

Single column
Gap: 16px

Examples

Basic List

<qariyb-event-list organization-id="01HWORG123ABC456"></qariyb-event-list>

Limited Events

<qariyb-event-list
  organization-id="01HWORG123ABC456"
  limit="6"
></qariyb-event-list>

Include Past Events

<qariyb-event-list
  organization-id="01HWORG123ABC456"
  show-past="true"
></qariyb-event-list>

List Layout with Many Events

<qariyb-event-list
  organization-id="01HWORG123ABC456"
  layout="list"
  limit="20"
></qariyb-event-list>

Dark Theme

<qariyb-event-list
  organization-id="01HWORG123ABC456"
  theme="dark"
  accent-color="#8b5cf6"
></qariyb-event-list>

Organization Landing Page

<!DOCTYPE html>
<html>
<head>
  <title>Our Events</title>
  <script>
    window.QariybConfig = {
      publishableKey: 'pk_live_...',
      theme: 'light',
      features: {
        showBranding: true,
      },
    };
  </script>
  <script src="https://js.qariyb.com/v1/qariyb.js"></script>
  <style>
    .hero {
      text-align: center;
      padding: 60px 20px;
      background: linear-gradient(135deg, #f0fdf4, #ecfdf5);
    }
    .events-section {
      max-width: 1200px;
      margin: 0 auto;
      padding: 40px 20px;
    }
  </style>
</head>
<body>
  <header class="hero">
    <h1>Community Events</h1>
    <p>Join our upcoming gatherings</p>
  </header>

  <section class="events-section">
    <qariyb-event-list
      organization-id="01HWORG123ABC456"
      limit="12"
    ></qariyb-event-list>
  </section>
</body>
</html>

With Analytics

<qariyb-event-list
  organization-id="01HWORG123ABC456"
  on-loaded="trackEventsViewed"
></qariyb-event-list>

<script>
  function trackEventsViewed(data) {
    gtag('event', 'view_item_list', {
      item_list_id: 'organization_events',
      items: data.events.map(event => ({
        item_id: event.id,
        item_name: event.title,
      })),
    });
  }

  document.addEventListener('qariyb:card:clicked', (e) => {
    gtag('event', 'select_item', {
      items: [{
        item_id: e.detail.data.event.id,
        item_name: e.detail.data.event.title,
      }],
    });
  });
</script>

Filter Tabs

<div class="tabs">
  <button onclick="showUpcoming()">Upcoming</button>
  <button onclick="showPast()">Past Events</button>
</div>

<qariyb-event-list
  id="events-list"
  organization-id="01HWORG123ABC456"
  show-past="false"
></qariyb-event-list>

<script>
  const list = document.getElementById('events-list');

  function showUpcoming() {
    list.setAttribute('show-past', 'false');
  }

  function showPast() {
    list.setAttribute('show-past', 'true');
  }
</script>

Dynamic Organization

<select id="org-select" onchange="changeOrganization()">
  <option value="01HWORG1">Organization 1</option>
  <option value="01HWORG2">Organization 2</option>
  <option value="01HWORG3">Organization 3</option>
</select>

<qariyb-event-list
  id="events-list"
  organization-id="01HWORG1"
></qariyb-event-list>

<script>
  function changeOrganization() {
    const orgId = document.getElementById('org-select').value;
    document.getElementById('events-list').setAttribute('organization-id', orgId);
  }
</script>

Nested Event Handling

The list contains <qariyb-event-card> components. Events from cards bubble up:

const list = document.querySelector('qariyb-event-list');

list.addEventListener('qariyb:card:loaded', (e) => {
  console.log('Card loaded:', e.detail.data.event.title);
});

list.addEventListener('qariyb:card:clicked', (e) => {
  console.log('Card clicked:', e.detail.data.event.title);
});

document.addEventListener('qariyb:checkout:success', (e) => {
  console.log('Purchase from list:', e.detail.data.order.id);
});

Empty State

When no events are found, the list shows a "No events available" message:

list.addEventListener('qariyb:list:loaded', (e) => {
  if (e.detail.data.events.length === 0) {
    showEmptyMessage('No events scheduled');
  }
});

Styling

Custom Container

<style>
  .events-wrapper {
    max-width: 1400px;
    margin: 0 auto;
    padding: 20px;
  }

  .events-wrapper qariyb-event-list {
    --qariyb-grid-min-width: 280px;
    --qariyb-grid-gap: 32px;
  }
</style>

<div class="events-wrapper">
  <qariyb-event-list organization-id="01HWORG..."></qariyb-event-list>
</div>

Theme Configuration

window.QariybConfig = {
  publishableKey: 'pk_live_...',
  theme: 'light',
  variables: {
    colorPrimary: '#4f46e5',
    borderRadius: '16px',
  },
  features: {
    showBranding: false, // Hide "Powered by Qariyb"
  },
};

Footer Branding

Control the "Powered by Qariyb" footer:

window.QariybConfig = {
  publishableKey: 'pk_live_...',
  features: {
    showBranding: true,  // Show footer (default)
    // showBranding: false, // Hide footer
  },
};

Loading States

Shows skeleton cards while loading:

window.QariybConfig = {
  publishableKey: 'pk_live_...',
  features: {
    skeletonLoading: true,  // Skeleton cards (default)
    // skeletonLoading: false, // Spinner instead
  },
};

Complete Example

<!DOCTYPE html>
<html>
<head>
  <title>All Events</title>
  <script>
    window.QariybConfig = {
      publishableKey: 'pk_live_...',
      theme: 'light',
      variables: {
        colorPrimary: '#059669',
        borderRadius: '12px',
      },
      features: {
        showBranding: true,
        skeletonLoading: true,
      },
    };
  </script>
  <script src="https://js.qariyb.com/v1/qariyb.js"></script>
  <style>
    body { font-family: system-ui, sans-serif; margin: 0; padding: 0; }
    header { background: #059669; color: white; padding: 40px 20px; text-align: center; }
    main { max-width: 1200px; margin: 0 auto; padding: 40px 20px; }
    .filters { display: flex; gap: 12px; margin-bottom: 24px; }
    .filter-btn { padding: 8px 16px; border: 1px solid #e5e7eb; border-radius: 8px; background: white; cursor: pointer; }
    .filter-btn.active { background: #059669; color: white; border-color: #059669; }
  </style>
</head>
<body>
  <header>
    <h1>Community Events</h1>
    <p>Find and register for our upcoming events</p>
  </header>

  <main>
    <div class="filters">
      <button class="filter-btn active" onclick="setFilter('upcoming')">Upcoming</button>
      <button class="filter-btn" onclick="setFilter('past')">Past Events</button>
    </div>

    <qariyb-event-list
      id="events"
      organization-id="01HWORG123ABC456"
      limit="12"
      on-loaded="handleLoaded"
      on-error="handleError"
    ></qariyb-event-list>
  </main>

  <script>
    const list = document.getElementById('events');
    const filterBtns = document.querySelectorAll('.filter-btn');

    function setFilter(type) {
      filterBtns.forEach(btn => btn.classList.remove('active'));
      event.target.classList.add('active');
      list.setAttribute('show-past', type === 'past' ? 'true' : 'false');
    }

    function handleLoaded(data) {
      console.log(`Loaded ${data.events.length} events`);
    }

    function handleError(data) {
      console.error('Failed to load events:', data.error);
    }

    document.addEventListener('qariyb:checkout:success', (e) => {
      console.log('Purchase:', e.detail.data.order.id);
      alert('Thank you for registering!');
    });
  </script>
</body>
</html>