Bootstrap Modal Pencere Kullanımı: İskelet, Seçenekler ve Olaylar

Modal nasıl çalışır: bilmeniz gereken kurallar

Modal; HTML, CSS ve JavaScript birlikte çalıştığında ortaya çıkan bir bileşendir. Derlenmiş CSS dosyasında .modal sınıfı position: fixed, display: none ve tüm ekranı kaplayan genişlik ile yükseklik alır; yani pencere sayfadaki her şeyin üstünde durur ve JavaScript onu gösterene kadar görünmez. Pencere açıldığında Bootstrap <body> öğesine modal-open sınıfını ekler ve sayfanın kendi kaydırmasını kaldırır; böylece kullanıcı kaydırdığında sayfa değil modalın içeriği kayar.

Belgenin özellikle vurguladığı birkaç sınır vardır. Bootstrap aynı anda yalnızca bir modal penceresini destekler; iç içe modal desteklenmez çünkü kötü bir kullanıcı deneyimi sayılır. position: fixed kullanıldığı için modal HTML kodunu mümkün olduğunca sayfanın üst düzeyine, örneğin <body> kapanışından hemen önceye koymanız önerilir; sabit konumlu başka bir öğenin içine yerleştirilen modal beklenmedik görüntü sorunları çıkarabilir. Mobil tarayıcılarda <body> üzerindeki overflow: hidden desteği sınırlı olduğundan, modalın en altına ya da en üstüne gelip kaydırmayı sürdürdüğünüzde arkadaki sayfa kaymaya başlayabilir; ayrıntı için Bootstrap 5.0: Browsers and devices sayfasına bakın.

Bir başka tuzak autofocus özniteliğidir. HTML anlamsal kuralları nedeniyle modalın içindeki bir alana autofocus eklemek işe yaramaz. Aynı etkiyi elde etmek için modal tamamen göründükten sonra tetiklenen shown.bs.modal olayını dinleyip odağı kendiniz taşırsınız:

var myModal = document.getElementById('myModal')
var myInput = document.getElementById('myInput')

myModal.addEventListener('shown.bs.modal', function () {
  myInput.focus()
})

Modal açılırken çalışan kayma ve solma animasyonu prefers-reduced-motion medya sorgusuna bağlıdır: kullanıcı işletim sisteminde hareketi azaltmayı seçtiyse derlenmiş CSS içindeki kural geçişi kapatır. Erişilebilirlik ayrıntıları için Bootstrap erişilebilirlik yazısına bakabilirsiniz.

Temel modal iskeleti ve canlı örnek

Bir modal üç katmandan oluşur. En dışta .modal kapsayıcısı, onun içinde genişliği ve kenar boşluğunu belirleyen .modal-dialog, en içte ise kenarlık, arka plan rengi ve köşe yuvarlaklığı taşıyan .modal-content bulunur. İçerik katmanını .modal-header, .modal-body ve isteğe bağlı .modal-footer parçalarına bölersiniz. Belge, iç boşluk (padding) gövdeden geldiği için .modal-body öğesini zorunlu sayar ve kullanıcıya her zaman açık bir kapatma yolu sunmanızı ister; başlıktaki kapatma butonu bunun en yaygın biçimidir.

Aşağıdaki örnekte buton, data-bs-target ile modalın id değerini gösterir. Modal kapsayıcısındaki .fade sınıfı açılış animasyonunu sağlar, tabindex="-1" pencerenin odak alabilmesine yarar, aria-labelledby ise ekran okuyuculara pencere başlığını bildirir. Kapatma işini data-bs-dismiss="modal" özniteliğini taşıyan her buton görür:

<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#ornekModal">
  Modalı aç
</button>

<div class="modal fade" id="ornekModal" tabindex="-1" aria-labelledby="ornekModalBaslik" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="ornekModalBaslik">Siparişi onayla</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Kapat"></button>
      </div>
      <div class="modal-body">
        <p>Sepetinizdeki 3 ürün için siparişi onaylıyor musunuz?</p>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Vazgeç</button>
        <button type="button" class="btn btn-primary">Onayla</button>
      </div>
    </div>
  </div>
</div>

Butona tıklandığında Bootstrap modalı gösterir, arkasına .modal-backdrop sınıflı yarı saydam bir katman ekler ve bu katmana tıklanınca pencereyi kapatır. Derlenmiş CSS dosyasında arka plan katmanı siyah renkte ve .show durumunda 0.5 opaklıkla tanımlıdır. Pencere kapandığında, onu açan buton hâlâ görünürse odak bu butona geri verilir; bu davranış Bootstrap v5.0.2 kaynak kodu: modal.js dosyasındaki tıklama işleyicisinde yer alır ve klavye kullanıcılarının sayfada kaybolmasını önler.

Erişilebilirlik için belge, .modal öğesine başlığı gösteren aria-labelledby eklemenizi ve isterseniz pencerenin açıklamasını aria-describedby ile vermenizi önerir. role="dialog" eklemeniz gerekmez; kaynak kod, pencere gösterilirken role="dialog" ve aria-modal özniteliklerini kendisi ekler, kapanırken kaldırır ve yerine aria-hidden koyar. ARIA rollerinin genel anlamı için ARIA rol ve öznitelikleri yazısına bakabilirsiniz.

Static backdrop: dışarı tıklayınca kapanmayan modal

Varsayılan davranışta karartılmış arka plana tıklamak veya Esc tuşuna basmak modalı kapatır. Kullanıcının bir seçim yapmadan pencereden çıkmasını istemediğiniz durumlarda, örneğin bir sözleşme onayında, data-bs-backdrop="static" verirsiniz. Esc tuşunu da devre dışı bırakmak için yanına data-bs-keyboard="false" eklenir. Belgedeki örnek bu iki özniteliği birlikte kullanır:

<div class="modal fade" id="onayModal" data-bs-backdrop="static" data-bs-keyboard="false" tabindex="-1" aria-labelledby="onayModalBaslik" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="onayModalBaslik">Kullanım koşulları</h5>
      </div>
      <div class="modal-body">
        <p>Devam etmek için koşulları kabul etmeniz gerekiyor.</p>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Reddet</button>
        <button type="button" class="btn btn-primary" data-bs-dismiss="modal">Kabul ediyorum</button>
      </div>
    </div>
  </div>
</div>

Static modda kullanıcı dışarı tıkladığında ya da klavye seçeneği kapalıyken Esc tuşuna bastığında pencere kapanmaz; bunun yerine hidePrevented.bs.modal olayı tetiklenir. Kaynak kod bu sırada modala kısa süreliğine modal-static sınıfını ekler; derlenmiş CSS bu sınıf varken diyaloğu scale(1.02) ile hafifçe büyütür, böylece kullanıcı pencerenin kapanmadığını görsel olarak fark eder. Static bir modalda mutlaka bir kapatma ya da karar butonu bulundurun, aksi hâlde kullanıcı pencereden çıkamaz.

Uzun içerik, kaydırılabilir gövde ve dikey ortalama

Modalın içeriği ekran yüksekliğini aştığında pencere sayfadan bağımsız olarak kendi içinde kayar; bu, .modal öğesinin overflow-y: auto kuralından gelir ve bütün pencere (başlık ve alt bilgi dahil) birlikte kayar. Başlığın ve alt bilginin sabit kalıp yalnızca gövdenin kaymasını istiyorsanız .modal-dialog öğesine .modal-dialog-scrollable sınıfını eklersiniz. Derlenmiş CSS bu sınıfla diyaloğa ekran yüksekliğinden kenar payı düşülmüş bir yükseklik verir ve .modal-body için overflow-y: auto tanımlar.

Pencerenin ekranın üst kısmında değil dikey olarak ortada durması için .modal-dialog-centered kullanılır. Bu sınıf diyaloğu flex kapsayıcıya çevirir ve align-items: center ile içeriği ortalar. İki sınıf birlikte de kullanılabilir:

<!-- Dikey ortalanmış modal -->
<div class="modal-dialog modal-dialog-centered">
  <div class="modal-content">...</div>
</div>

<!-- Dikey ortalanmış ve gövdesi kaydırılabilir modal -->
<div class="modal-dialog modal-dialog-centered modal-dialog-scrollable">
  <div class="modal-content">...</div>
</div>

Modal açıkken içeriğin yüksekliği değişirse, örneğin bir bölüm genişletildiğinde ya da sonradan veri yüklendiğinde, belge myModal.handleUpdate() çağırmanızı söyler. Bu yöntem bir kaydırma çubuğu ortaya çıktığında pencerenin konumunu yeniden ayarlar.

Modal gövdesinde ızgara kullanmak da mümkündür. Belge, .modal-body içine bir .container-fluid yerleştirip ardından normal .row ve .col-* sınıflarını kullanmanızı önerir. Izgara sisteminin kendisi için Bootstrap grid sistemi yazısına bakabilirsiniz.

Modal boyutları ve tam ekran modal

Varsayılan modal, 576px ve üstü genişlikteki ekranlarda en fazla 500px genişliğindedir; daha dar ekranlarda kenarlardan küçük bir pay bırakarak ekrana yayılır. Üç boyut sınıfı .modal-dialog öğesine eklenir ve belirli kırılma noktalarından itibaren devreye girer; böylece dar ekranlarda yatay kaydırma çubuğu oluşmaz:

Tablodaki son sütun derlenmiş CSS dosyasındaki medya sorgularından okunmuştur. Bu genişlikler Sass tarafında $modal-sm, $modal-md, $modal-lg ve $modal-xl değişkenlerinden gelir; değerleri değiştirmek isterseniz Sass ile özelleştirme yazısındaki içe aktarma sırasını izlemeniz gerekir.

Modalın bütün görüş alanını kaplaması için .modal-fullscreen sınıfı vardır. Yalnızca belirli bir ekran genişliğinin altında tam ekran olmasını istiyorsanız kırılma noktalı sürümleri kullanırsınız: .modal-fullscreen-sm-down 576px altında, -md-down 768px altında, -lg-down 992px altında, -xl-down 1200px altında, -xxl-down ise 1400px altında devreye girer. Bu sınıflar Sass içindeki $breakpoints haritası üzerinden bir döngüyle üretilir. Bir boyut sınıfıyla birlikte kullanmak, örneğin masaüstünde büyük, telefonda tam ekran bir pencere elde etmek mümkündür:

<div class="modal fade" id="raporModal" tabindex="-1" aria-labelledby="raporModalBaslik" aria-hidden="true">
  <div class="modal-dialog modal-lg modal-fullscreen-md-down">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="raporModalBaslik">Aylık rapor</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Kapat"></button>
      </div>
      <div class="modal-body">
        <div class="container-fluid">
          <div class="row">
            <div class="col-md-6">Satışlar</div>
            <div class="col-md-6">İadeler</div>
          </div>
        </div>
      </div>
    </div>
  </div>
</div>

Kırılma noktalarının hangi genişliklere karşılık geldiğini Bootstrap breakpoint yazısında ayrıntılı olarak bulabilirsiniz.

Tetikleyen butona göre modal içeriğini değiştirmek

Aynı modalı açan birden fazla buton olduğunda içeriği her seferinde baştan yazmanıza gerek yoktur. show.bs.modal olayının nesnesinde relatedTarget özelliği bulunur ve pencere bir tıklamayla açıldıysa bu özellik tıklanan öğeyi verir. Butonlara kendi data-bs-* özniteliğinizi koyup olay içinde okuyarak başlığı ya da form alanlarını güncellersiniz. Belgedeki örneği uyarladık:

<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#mesajModal" data-bs-alici="Ayşe">Ayşe'ye yaz</button>
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#mesajModal" data-bs-alici="Mehmet">Mehmet'e yaz</button>

<div class="modal fade" id="mesajModal" tabindex="-1" aria-labelledby="mesajModalBaslik" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="mesajModalBaslik">Yeni mesaj</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Kapat"></button>
      </div>
      <div class="modal-body">
        <form>
          <div class="mb-3">
            <label for="alici-adi" class="col-form-label">Alıcı:</label>
            <input type="text" class="form-control" id="alici-adi">
          </div>
          <div class="mb-3">
            <label for="mesaj-metni" class="col-form-label">Mesaj:</label>
            <textarea class="form-control" id="mesaj-metni"></textarea>
          </div>
        </form>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Kapat</button>
        <button type="button" class="btn btn-primary">Gönder</button>
      </div>
    </div>
  </div>
</div>

var mesajModal = document.getElementById('mesajModal')
mesajModal.addEventListener('show.bs.modal', function (event) {
  // Modali acan buton
  var button = event.relatedTarget
  var alici = button.getAttribute('data-bs-alici')

  mesajModal.querySelector('.modal-title').textContent = alici + ' icin yeni mesaj'
  mesajModal.querySelector('.modal-body input').value = alici
})

Burada data-bs-alici Bootstrap’in tanıdığı bir seçenek değildir; yalnızca sizin okuduğunuz bir veri özniteliğidir. Belge bu noktada gerekirse olayın içinde sunucuya bir istek yapıp içeriği yanıt geldikten sonra güncelleyebileceğinizi de belirtir. Modalı JavaScript ile açarken de relatedTarget verebilirsiniz: myModal.show(butonOgesi) çağrısında verdiğiniz öğe olay nesnesinde aynı özellikle görünür. Form alanlarının stilleri için Bootstrap form-control yazısına bakabilirsiniz.

İki modal arasında geçiş

Aynı anda iki modal açık tutamazsınız, fakat birinden diğerine geçebilirsiniz. Örneğin giriş penceresinden “şifremi unuttum” penceresine geçmek için ilk modalın içindeki butona hem data-bs-toggle="modal" ile ikinci pencerenin hedefini hem de data-bs-dismiss="modal" verirsiniz. Belge bu yöntemin yalnızca iki ayrı modal arasında geçiş yaptığını, ikisini birlikte açmadığını özellikle vurgular:

<div class="modal fade" id="girisModal" aria-hidden="true" aria-labelledby="girisModalBaslik" tabindex="-1">
  <div class="modal-dialog modal-dialog-centered">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="girisModalBaslik">Giriş yap</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Kapat"></button>
      </div>
      <div class="modal-body">Giriş formu burada yer alır.</div>
      <div class="modal-footer">
        <button class="btn btn-link" data-bs-target="#sifreModal" data-bs-toggle="modal" data-bs-dismiss="modal">Şifremi unuttum</button>
      </div>
    </div>
  </div>
</div>
<div class="modal fade" id="sifreModal" aria-hidden="true" aria-labelledby="sifreModalBaslik" tabindex="-1">
  <div class="modal-dialog modal-dialog-centered">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="sifreModalBaslik">Şifre sıfırlama</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Kapat"></button>
      </div>
      <div class="modal-body">E-posta adresinizi girin.</div>
      <div class="modal-footer">
        <button class="btn btn-primary" data-bs-target="#girisModal" data-bs-toggle="modal" data-bs-dismiss="modal">Girişe dön</button>
      </div>
    </div>
  </div>
</div>
<a class="btn btn-primary" data-bs-toggle="modal" href="#girisModal" role="button">Giriş penceresini aç</a>

Son satırdaki bağlantı, hedefi data-bs-target yerine href="#girisModal" ile verir; belge iki yöntemi de kabul eder. Bağlantı ile tetiklendiğinde Bootstrap varsayılan bağlantı davranışını engeller, böylece adres çubuğuna #girisModal eklenmez ve sayfa zıplamaz.

JavaScript ile modal: seçenekler, yöntemler ve olaylar

Veri öznitelikleri yeterli olmadığında modalı kodla oluşturursunuz. Yapıcı, birinci argüman olarak modal öğesini, ikinci argüman olarak isteğe bağlı bir seçenek nesnesini alır. Seçenekleri veri özniteliğiyle de verebilirsiniz; seçenek adının başına data-bs- eklenir, data-bs-backdrop gibi. Kaynak koddaki Default nesnesi ve belge aynı üç seçeneği listeler:

var myModal = new bootstrap.Modal(document.getElementById('myModal'), {
  keyboard: false
})

myModal.show()
myModal.hide()
myModal.toggle()
myModal.handleUpdate()
myModal.dispose()

// Ogeye bagli ornegi almak
var modal = bootstrap.Modal.getInstance(document.getElementById('myModal'))
// Yoksa olusturarak almak
var modal2 = bootstrap.Modal.getOrCreateInstance(document.querySelector('#myModal'))

show(), hide() ve toggle() yöntemleri eşzamansızdır: geçiş başlar başlamaz çağırana döner, animasyonun bitmesini beklemez. Ayrıca geçiş sürerken yapılan yeni bir çağrı yok sayılır; kaynak kodda show(), pencere zaten açıksa ya da bir geçiş sürüyorsa hiçbir şey yapmadan döner. Animasyon bittikten sonra bir iş yapmanız gerekiyorsa ilgili olayı dinlersiniz. dispose() öğe üzerinde saklanan örnek verisini siler; getInstance() öğeye bağlı örneği verir, getOrCreateInstance() ise örnek yoksa yenisini oluşturur.

Modal olaylarının tamamı .modal öğesinin kendisinde tetiklenir:

“show” ve “hide” gibi mastar biçimli olaylar preventDefault() desteği sunar. Örneğin form kaydedilmemişse hide.bs.modal içinde event.preventDefault() çağırarak pencerenin kapanmasını durdurabilirsiniz. Olay modelinin, getOrCreateInstance ve Default nesnesinin bütün bileşenlerde ortak çalışması Bootstrap JavaScript API yazısında anlatılır.

var formModal = document.getElementById('formModal')
formModal.addEventListener('hide.bs.modal', function (event) {
  if (formModal.querySelector('form').dataset.degisti === 'evet') {
    event.preventDefault() // kaydedilmemis degisiklik varken kapatma
  }
})

Modal içinde tooltip, popover ve video

Modalın içine ipucu (tooltip) ve açılır kutu (popover) koyabilirsiniz; modal kapandığında içindeki tooltip ve popoverlar da otomatik olarak gizlenir. Bu iki bileşen ayrıca başlatılmayı gerektirdiğinden kurulum adımları için tooltip ve popover yazısına bakın. Modala YouTube videosu gömmek ise Bootstrap içinde olmayan ek JavaScript gerektirir; belge, pencere kapandığında oynatmanın kendiliğinden durmayacağını ve bunun için ayrıca kod yazmanız gerektiğini belirtir.

Modal, yan panel olarak açılan offcanvas bileşeni ile benzer bir arka plan katmanı kullanır. İçeriği ekranın kenarından kayarak gelen bir menü istiyorsanız offcanvas, kullanıcıdan karar bekleyen ortadaki bir pencere istiyorsanız modal daha uygundur.

Sık yapılan hatalar

• JavaScript dosyasını eklememek: Modal yalnızca CSS ile açılmaz. Sayfada bootstrap.bundle.min.js ya da bootstrap.min.js yüklü olmalıdır. Kurulum için CDN kurulum yazısına bakın.
• v4 öznitelikleri: Bootstrap 4 kodundan kalan data-toggle="modal" ve data-target v5’te çalışmaz; doğru adlar data-bs-toggle ve data-bs-target’tır. Değişikliklerin listesi Bootstrap 4’ten 5’e geçiş yazısında yer alır.
• Hedef ile kimliğin uyuşmaması: data-bs-target="#ornekModal" değeri modalın id değeriyle birebir aynı olmalı ve başında # bulunmalıdır.
• Modalı sabit konumlu bir öğenin içine koymak: Sabit bir menü ya da kenar çubuğunun içine yerleştirilen modal üstte görünmeyebilir. Modalı belgenin üst düzeyine taşıyın.
• İkinci modalı birincinin üstünde açmaya çalışmak: Bootstrap iç içe modal desteklemez. Geçiş gerekiyorsa yukarıdaki toggle yöntemini kullanın.
• Aynı butona iki bileşen bağlamak: Belge bir öğede yalnızca tek bir veri özniteliği takımı kullanmanızı söyler; aynı butondan hem tooltip hem modal tetiklenemez. Tooltip için butonu bir kapsayıcıya sarın.
• Geçiş bitmeden ikinci çağrı yapmak: hide() çağrısından hemen sonra show() çağırmak yok sayılabilir. Sıralı işlemleri hidden.bs.modal olayına bağlayın.

Bootstrap’in çalışmadığı genel durumların listesi için Bootstrap çalışmıyor yazısına de bakabilirsiniz.

Sık Sorulan Sorular

Bootstrap modalı jQuery olmadan açılır mı?

Evet. Bootstrap 5 jQuery bağımlılığını kaldırmıştır; modal veri öznitelikleriyle ya da new bootstrap.Modal() ile saf JavaScript üzerinden çalışır. Sayfada jQuery bulunursa Bootstrap bileşenleri ayrıca jQuery eklentisi olarak da kaydeder.

Modal dışına tıklayınca kapanmasını nasıl engellerim?

.modal öğesine data-bs-backdrop="static" verin ya da JavaScript ile backdrop: 'static' seçeneğini kullanın. Esc tuşunu da kapatmak için data-bs-keyboard="false" ekleyin.

Modalı sayfa yüklenince otomatik nasıl açarım?

Bunun için ayrı bir veri özniteliği yoktur. Sayfa yüklendikten sonra new bootstrap.Modal(document.getElementById('kimlik')).show() çağırmanız yeterlidir.

Modal içindeki inputa otomatik odak nasıl verilir?

autofocus modal içinde etkili olmaz. shown.bs.modal olayını dinleyip alanın focus() yöntemini çağırın.

Modal genişliğini nasıl ayarlarım?

.modal-dialog öğesine .modal-sm, .modal-lg veya .modal-xl ekleyin; tam ekran için .modal-fullscreen ya da kırılma noktalı -down sürümlerini kullanın. Farklı bir genişlik gerekiyorsa Sass değişkenlerini değiştirebilirsiniz.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Bootstrap öğrenme rehberi · Bootstrap JavaScript API · Offcanvas yan menü · Toast bildirimleri · Tooltip ve popover · JavaScript öğrenme rehberi