EN

Komponen & pembantu

Bahan penyusun setiap halaman, dan pembantu JavaScript kecil yang dipakai bersama.

Katalog komponen

Rujukan utama Anda adalah UI Kit › Komponen. Setiap komponen di sana adalah contoh hidup dengan dua tombol di bawahnya:

  • Lihat kode menampilkan HTML persis dari contoh di atasnya, jadi keduanya tidak mungkin berbeda.
  • Salin menyalin HTML itu ke papan klip, siap ditempel ke halaman di src/pages/.

Halaman UI Kit lainnya (grafik, formulir, pemilih, unggah, tabel data, dan lainnya) bekerja dengan cara yang sama: setiap contoh disertai kodenya.

Kelas komponen

Komponen ini bisa dipakai di halaman mana pun — gayanya ada di assets/css/selaras.css dan perilaku bersamanya di assets/js/selaras.js, yang sudah dimuat setiap halaman.

KomponenKelas utamaCatatan
Tombol.sl-btn .sl-btn-primary .sl-btn-light .sl-btn-sm .sl-icon-btn .sl-linkbtnWarna, ukuran, tombol ikon saja, dan tombol bergaya teks
Lencana & status.sl-status .sl-status--success .sl-chip .sl-kbdWarna: success, warning, danger, info, neutral, secondary
Avatar.sl-av .sl-stack .sl-person .sl-thumbInisial, kelompok, avatar dengan nama, ubin gambar
Peringatan.sl-alert .sl-alert--info data-sl-dismissEmpat warna; tombol tutup menghapus peringatan
Formulir.sl-field .sl-control .sl-help .sl-field-err .sl-addonLabel, isian, teks bantuan, dan pesan galat
Pilihan.sl-choices .sl-check .sl-radio .sl-switch .sl-segKotak centang, radio, sakelar, kontrol segmen
Isian khusus.sl-input .sl-pass .sl-meter .sl-otpPencarian, sandi dengan pengukur kekuatan, kode sekali pakai
Kartu & KPI.sl-card .sl-card-head .sl-card-title .sl-kpi .sl-kpi-valuePanel dan ubin statistik
Tab.sl-tabs .sl-tabs-panelKlik dan tombol panah ditangani selaras.js
Tabel.sl-table-wrap .sl-table .sl-pagerBisa digeser ke samping di layar kecil
Progres & memuat.sl-progress .sl-spin .sl-skelBilah, pemutar, dan placeholder saat memuat
Menu.sl-menuGaya untuk .dropdown-menu Bootstrap
Modal & toast.sl-modal .sl-modal-head .sl-modal-body .sl-modal-foot .sl-toastModal dan tooltip Bootstrap yang sudah diberi gaya
Keadaan kosong.sl-emptyIkon, pesan, dan aksi

Katalog masih punya lebih banyak: breadcrumb dan penomoran halaman, akordeon, list group, linimasa, carousel, popover, dan offcanvas. Ikonnya Tabler Icons, ditulis sebagai <i class="ti ti-home"></i>. Bootstrap 5 dimuat di setiap halaman, jadi kelas grid dan utilitasnya (row, col-md-6, d-flex, gap-3…) juga bisa dipakai.

Pembantu JavaScript

Tiga pembantu tersedia di setiap halaman, dari assets/js/selaras.js:

PembantuFungsinya
window.slChartMenggambar grafik ApexCharts yang mengikuti tema aktif serta mode terang/gelap.
window.slFmtMemformat angka, uang, tanggal, dan jam sesuai bahasa halaman.
window.slI18nMenerjemahkan teks yang ditulis skrip Anda.

Grafik — window.slChart

Grafik memakai ApexCharts. Gambar lewat window.slChart, maka warnanya diambil dari tema aktif dan grafik digambar ulang sendiri saat tema atau mode terang/gelap berganti.

FungsiFungsinya
draw(selector, factory)Menggambar grafik ke dalam elemen. Fungsi pembuatnya mengembalikan opsi ApexCharts dan dijalankan ulang setiap kali tema berganti.
base()Tampilan bersama: font, warna sumbu dan grid, tanpa toolbar, tanpa legenda, tanpa label data.
merge(a, b)Menggabungkan opsi Anda secara mendalam ke base().
colors()Warna tema saat ini dalam nilai hex (seri, teks, garis, permukaan).
tip(title, rows)Membuat tooltip bergaya Selaras untuk opsi tooltip.custom.

Contoh — grafik batang jumlah pesanan per hari. Tambahkan elemen ini ke halaman Anda:

HTML
<div class="sl-card">
  <div id="chart-orders" role="img" aria-label="Orders per day, Sep 21 to Sep 27"></div>
</div>

Lalu gambar dari skrip halaman Anda (berkas yang tercantum di meta "scripts" halaman, yang dimuat setelah selaras.js):

JavaScript
(function () {
  var K = window.slChart, F = window.slFmt, _t = window.slI18n.t;
  if (!K) return;   // ApexCharts is not loaded on this page

  var days = ['2026-09-21', '2026-09-22', '2026-09-23', '2026-09-24',
              '2026-09-25', '2026-09-26', '2026-09-27'];
  var orders = [42, 51, 47, 63, 58, 71, 39];

  K.draw('#chart-orders', function () {
    // series: C.primary, C.secondary, C.d3, C.d4
    // interface: C.ink, C.ink3, C.ink4, C.line, C.lineStrong, C.surface
    var C = K.colors();
    return K.merge(K.base(), {
      chart: { type: 'bar', height: 260 },
      series: [{ name: _t('Orders'), data: orders }],
      colors: [C.primary],
      xaxis: { categories: days.map(function (d) { return F.short(d); }) },
      yaxis: { labels: { formatter: function (v) { return F.num(v); } } },
      tooltip: {
        custom: function (o) {
          var i = o.dataPointIndex;
          return K.tip(F.date(days[i]), [
            { c: C.primary, n: _t('Orders'), v: F.num(orders[i]) }
          ]);
        }
      }
    });
  });
})();

Pakai warna seri dengan urutan tetap — pertama primary, lalu secondary, lalu warna data ketiga dan keempat — supaya jenis data yang sama selalu berwarna sama di semua grafik. UI Kit › Grafik berisi 13 jenis grafik yang dibuat dengan cara ini, masing-masing dengan kodenya.

Di mana grafik tersedia

ApexCharts dan window.slChart dimuat di setiap halaman yang punya sidebar (src/layout.html). Halaman masuk, halaman galat, dan halaman toko tidak memuatnya.

Angka, uang, dan tanggal — window.slFmt

Format setiap angka lewat window.slFmt, jangan ditulis manual. Formatnya mengikuti bahasa halaman: di halaman Inggris uang dalam dolar dengan sen, di halaman Indonesia dalam rupiah tanpa desimal, dan tanggal serta jam memakai urutan masing-masing bahasa.

JavaScript
var F = window.slFmt;
//                                  English          Indonesian
F.money(1234.5);                 // '$1,234.50'      'Rp1.235'
F.num(5717);                     // '5,717'          '5.717'
F.pct(12.4, 1);                  // '12.4%'          '12,4%'
F.moneyShort(1500);              // '$1.5k'          'Rp1,5rb'
F.date('2026-09-23');            // 'Sep 23, 2026'   '23 Sep 2026'
F.short('2026-09-23');           // 'Sep 23'         '23 Sep'
F.dayDate('2026-09-23');         // 'Wed, Sep 23'    'Rab, 23 Sep'
F.clock('2026-09-23T14:05');     // '2:05 PM'        '14.05'

F.parse('1,234.50');             // 1234.5  — an amount typed in a field
F.parse('');                     // null    — empty field
F.parse('abc');                  // NaN     — not an amount

Tanggal boleh berupa teks ISO atau objek Date. F.lang memberi tahu bahasa halaman ('en' atau 'id'), dan F.cur simbol mata uangnya. Pembantu lain — int, bigMoney, monthYear, span, clockRange, hour, time, loose — dijelaskan dalam komentar singkat di awal assets/js/selaras.js.

Teks di skrip — window.slI18n

Teks yang ditulis JavaScript Anda dilewatkan ke window.slI18n, supaya bisa diterjemahkan. Di halaman Inggris, teksnya dikembalikan apa adanya.

JavaScript
var _t = window.slI18n.t, _tn = window.slI18n.tn;

_t('Saved');                                   // 'Saved' (or its translation)
_t('Sent to {name}', { name: 'Ava' });         // placeholders are filled in
_tn(3, '{n} item', '{n} items');               // '3 items' (singular or plural)
window.slI18n.key('my-app-data');              // a storage key per language

Cara menyimpan dan menambah terjemahan dijelaskan di Bahasa.

Widget siap pakai

Tiga widget buatan Selaras tidak butuh pustaka tambahan. Pemilih tanggal dan pengunggah masing-masing punya skrip — tambahkan ke meta "scripts" halaman; toast cukup markup dan beberapa baris JavaScript.

Pemilih tanggal

assets/js/sl-datepicker.js memilih satu tanggal atau rentang tanggal dan bisa dipakai sepenuhnya dengan keyboard. Tandai isiannya dengan data-sl-datepicker:

HTML
<div class="sl-field">
  <label for="dueDate">Tenggat</label>
  <div class="sl-dp" data-sl-datepicker data-min="2026-01-01">
    <input class="sl-control" id="dueDate" type="text" autocomplete="off">
    <button class="sl-dp-toggle" type="button" aria-label="Choose due date">
      <i class="ti ti-calendar" aria-hidden="true"></i>
    </button>
  </div>
</div>
  • data-mode="range" memilih tanggal mulai dan tanggal akhir; data-min dan data-max membatasi tanggal yang bisa dipilih (format ISO).
  • Tanggal yang dipilih disimpan sebagai teks ISO di data-value pada elemen .sl-dp (data-start dan data-end untuk rentang), dan isiannya memicu event change.
  • Pemakai juga bisa mengetik tanggal langsung di isian; tanggal itu diperiksa saat isian kehilangan fokus.
  • Isian yang sudah ada disiapkan saat skrip dimuat. Untuk isian yang ditambahkan belakangan, panggil window.slDatepicker.setup(element).
JavaScript
document.getElementById('dueDate').addEventListener('change', function (e) {
  var picker = e.target.closest('[data-sl-datepicker]');
  var iso = picker.getAttribute('data-value');   // '2026-10-06'
});

Halaman demo mengisi data-today dengan tanggal tetap supaya contohnya selalu tampak sama. Hapus atribut itu dan pemilih memakai tanggal sebenarnya.

Unggah berkas

assets/js/sl-upload.js menangani seret-lepas atau pilih berkas, memeriksa jenis dan ukuran dengan alasan yang jelas bila berkas ditolak, serta menampilkan bilah progres dan pratinjau gambar per berkas:

HTML
<div class="sl-upload" data-sl-upload
     data-types="image/png,image/jpeg,application/pdf" data-max-mb="5" data-max-files="6">
  <input class="visually-hidden" type="file" id="files" multiple accept=".png,.jpg,.jpeg,.pdf">
  <label class="sl-upload-zone" for="files">
    <span class="sl-upload-icon" aria-hidden="true"><i class="ti ti-cloud-upload"></i></span>
    <strong>Lepas berkas di sini atau <span class="sl-upload-browse">pilih berkas</span></strong>
    <small>PNG, JPG or PDF · up to 5 MB each</small>
  </label>
  <ul class="sl-upload-list"></ul>
</div>
  • data-types berisi jenis MIME yang diizinkan, data-max-mb batas ukuran per berkas, dan data-max-files jumlah berkas. Semuanya opsional.
  • Saat satu berkas selesai, elemen .sl-upload memicu event sl-upload:done dengan File di event.detail.
  • Untuk pengunggah yang ditambahkan belakangan, panggil window.slUploadSetup(element).
Unggahannya disimulasikan

Tidak ada berkas yang keluar dari browser. Untuk mengirim berkas ke server Anda, ganti fungsi upload() di sl-upload.js dengan panggilan fetch atau XMLHttpRequest Anda sendiri.

Toast

Toast adalah pesan singkat di pojok bawah, misalnya setelah menyimpan. Pasang satu wadah di halaman:

HTML
<div class="sl-toast-wrap" role="status" aria-live="polite">
  <div class="sl-toast" id="myToast" hidden>
    <i class="ti ti-circle-check" aria-hidden="true"></i>
    <span id="myToastMsg"></span>
  </div>
</div>

Toast muncul meluncur saat mendapat kelas is-in. Fungsi minimal untuk menampilkannya selama enam detik:

JavaScript
var toastTimer;
function showToast(msg) {
  var el = document.getElementById('myToast');
  document.getElementById('myToastMsg').textContent = msg;
  el.hidden = false;
  requestAnimationFrame(function () { el.classList.add('is-in'); });
  clearTimeout(toastTimer);
  toastTimer = setTimeout(function () {
    el.classList.remove('is-in');
    setTimeout(function () { el.hidden = true; }, 220);
  }, 6000);
}

Tidak ada fungsi toast global — setiap aplikasi punya fungsi kecilnya sendiri. Untuk versi dengan tombol Urungkan yang berhenti sejenak saat disorot atau difokus, salin toast() dari assets/js/ecommerce.js. Untuk toast bergaya dialog, UI Kit › SweetAlert menampilkan SweetAlert2 yang tampilannya sudah diselaraskan.

Nama kelas

  • Setiap kelas komponen Selaras berawalan sl-. Keadaan memakai kelas is-, seperti is-in atau is-done.
  • Beri kelas buatan Anda awalan sendiri (misalnya app-). Dengan begitu kelasnya tidak akan bertabrakan dengan kelas Selaras atau Bootstrap, sekarang maupun setelah pembaruan.
  • Kelas khusus satu halaman di Selaras memakai awalan halaman yang pendek setelah sl- (misalnya sl-cx- untuk katalog komponen). Lakukan hal yang sama bila halaman Anda butuh gaya sendiri.
  • Kulit untuk pustaka pihak ketiga (FullCalendar, DataTables, Flatpickr, dan lainnya) menyasar kelas milik pustaka itu sendiri. Masing-masing berada di bawah komentar judulnya sendiri di selaras.css.

Aksesibilitas

Komponennya sudah dilengkapi dukungan papan ketik dan atribut ARIA yang tepat, jadi Anda mulai dari markup yang aksesibel:

  • Tab — tombol panah, Home, dan End berpindah antar-tab; hanya tab terpilih yang masuk urutan Tab.
  • Pilihan panel pengaturan tampilan — pilihan tema dan mode berperilaku sebagai grup radio dan bisa dipakai dengan tombol panah.
  • Peringatan — menutup kotak peringatan memindahkan fokus ke elemen berikutnya, bukan ke awal halaman.
  • Modal, dropdown, offcanvas, tooltip, dan popover memakai penanganan papan ketik dan fokus bawaan Bootstrap.
  • Pemilih tanggal — mengikuti pola dialog pemilih tanggal WAI-ARIA: tombol panah, Page Up/Down untuk pindah bulan, Enter untuk memilih, Escape untuk menutup.
  • Unggah berkas — isian berkas aslinya tetap bisa dijangkau dengan papan ketik, dan hasilnya diumumkan ke pembaca layar.
  • Toast diumumkan lewat wilayah aria-live.
  • Grafik punya role="img" dan ringkasan teks di aria-label; grafik di UI Kit › Grafik juga bisa ditampilkan sebagai tabel.
  • Fokus selalu terlihat saat Anda memakai papan ketik, animasi dimatikan bila sistem meminta gerak dikurangi, dan warna teks kelima tema memenuhi kontras WCAG AA di mode terang maupun gelap.

Saat membuat markup baru, pertahankan kebiasaan yang sama: beri tombol ikon saja aria-label, tandai ikon dekoratif dengan aria-hidden="true", dan hubungkan setiap isian ke <label>.