SweetAlert2のパラメータ（引数）の使い方まとめ | 使えるキー情報の使用頻度順一覧

2019-04-12 2019-12-11

JavaScriptのSweetAlert2ライブラリを使う事で、キレイでカッコいいダイアログを表示する事ができます。

alert・confirm・promptといったダイアログを使った場合と比較すると、SweetAlert2のダイアログはとてもスタイリッシュ！雲泥の差があります。

過去記事SweetAlert2を使ってキレイでリッチなJavaScriptダイアログ表示を実現する方法

2019.4.9

JavaScriptのalert、confirm、promptに変わるダイアログ表示をすることができるSweetAlertについてご紹介します。SweetAlertの豊富な機能を用いて簡単にキレイにカッコいいダイアログを実現できます。...

このSweetAlert2ライブラリですが、

マニュアルが英語で読みたくない（マニュアル）

できる事が多いのは良いけど、色々ありすぎてよく分からない

という事が多々あります。（私は大いにありました）

そこで、SweetAlert2でよく使う（使える）引数を独断と偏見で分けてみました。使えるもの順にサンプルコード・表示イメージと合わせてまとめましたので、参考になれば幸いです！

補足

本ページはSweetAlert2のバージョン8をベースに記載しています。
バージョン9においては一部大幅な変更が加えられているものがあるため、バージョン8で使用できていたものがバージョン9では使えなくなっているものもあります。詳しくは本家サイトをご確認ください。

例）typeはバージョン8まで利用可能　→　バージョン9からはiconに変更（typeの廃止）

よく使う基本的な引数（使用頻度：高）

タイトルの表示（title/titleText)

Swal.fire({
  title: 'タイトルをここに設定'
});

title/titleTextは、タイトルとして表示する文字列を設定するための引数。

titleとtitleTextの両方設定した場合、titleTextが優先される様子。titleはHTMLタグを利用可能。titleTextはHTMLタグを利用不可。

説明部分の表示（text/html）

Swal.fire({
  title: 'タイトルをここに設定'
, html : 'descriptionをここに設定。
HTMLタグも有効'
});

text/htmlは、ダイアログに表示したいメッセージや説明文を設定するための引数。

textとhtmlの両方設定した場合、textが優先される様子。htmlはHTMLタグを利用可能。textはHTMLタグを利用不可。

アイコンの表示（type）

Swal.fire({
  title: 'タイトルをここに設定'
, html : 'descriptionをここに設定。
HTMLタグも有効'
, type : 'info'
});

typeは、ダイアログにアイコンを表示したい場合に設定する引数。設定可能なアイコンは次の5種類。

warning：注意して欲しいメッセージを表示したい場合に有効
error：エラーや想定外の動きをした場合に表示すると有効
success：処理が正常終了した場合に表示すると有効
info：情報として何かを表示したい場合に有効
question：確認メッセージを表示したい場合に有効

ダイアログを自動的に閉じる設定（timer）

Swal.fire({
  title: 'タイトル'
, html : 'descriptionはタイトルの横に表示される'
, type : 'success'
, timer : '3000'    //3秒後に閉じる
});

timerは、ダイアログを指定時間経過後に自動的に閉じたい場合に設定する引数。時間指定はミリ秒単位（1秒の場合は1000を設定）。

後述のtoastと合わせて使用したり、完了ダイアログを自動的に閉じたい場合に利用すると良い。

ダイアログ枠外のクリック許可設定（allowOutsideClick）

Swal.fire({
  title: 'タイトル'
, html : 'descriptionはタイトルの横に表示される'
, type : 'success'
, allowOutsideClick : false   //枠外クリックは許可しない
});

allowOutsideClickは、ダイアログの枠外をクリックした際に、ダイアログを閉じないようにするための引数。デフォルト設定はtrueで、枠外をクリックするとダイアログが自動的に閉じられる。

ダイアログをモーダル形式で表示したい（ダイアログ表示中は他の操作をさせたくない）場合や、枠外をクリックしした際の処理を考慮したくない場合は、この設定をfalseにすると良い。

Escキーの許可設定（allowEscapeKey）

allowEscapeKeyは、ダイアログ表示中にEscキーを押した際に、ダイアログを閉じないようにするための引数。デフォルト設定はtrueで、Escキーを押すとダイアログが自動的に閉じられる。

意図せずにダイアログが閉じられないようにするために、allowOutsideClickと合わせて設定すると良い。

確認ボタンの表示有無＆ボタンに表示するテキストの設定（showConfirmButton、confirmButtonText）

Swal.fire({
  title: 'タイトル'
, html : 'textを入力してください。'
, showConfirmButton : true
, confirmButtonText : '確認！'
}).then(function(result) {
  console.log(result);
});

showConfirmButtonは、確認ボタンの表示・非表示を指定する引数。デフォルトはtrueなので、確認ボタンは表示される。

confirmButtonTextは、確認ボタンに表示するテキストを指定するための。デフォルトは'OK'。

基本的に確認ボタンは表示すると思われるため、confirmButtonTextでボタンに表示する文字を設定すると良い。

キャンセルボタンの表示有無＆ボタンに表示するテキストの設定（showCancelButton、cancelButtonText）

Swal.fire({
  title: 'タイトル'
, html : 'textを入力してください。'
, showCancelButton : true
, cancelButtonText : 'やめる'
}).then(function(result) {
  console.log(result);
});

showCancelButtonでは、キャンセルボタンの表示・非表示を指定するための引数。デフォルトはfalseなので、キャンセルボタンは表示されない。

cancelButtonTextでは、キャンセルボタンに表示するテキストを指定するための引数。デフォルトは'Cancel'。

ユーザに処理実行を確認させるダイアログを表示するような場合、この引数を使用してボタンの表示とボタンに表示するテキストを指定する。

確認ボタン時の処理前にバリデーション等の処理を入れる設定（preConfirm)

次のshowLoaderOnConfirmと合わせて説明。

確認ボタンクリック時に処理中アイコンを表示する設定（showLoaderOnConfirm）

Swal.fire({
  title: '何か入力してね'
, input: 'text'
, showCancelButton: true
, confirmButtonText: '実行'
, showLoaderOnConfirm: true
, preConfirm: function(inputStr) {
    console.log('preConfirm起動');
    
    //バリデーションを入れたりしても良い
    if (inputStr !== 'aaa') {
      return Swal.showValidationMessage('aaaを入力してね');
    }
    
    //ローディングを表示させるために3秒スリープ
    var sleep = function(sec) {
        return new Promise(resolve => {
          setTimeout(resolve, sec * 1000);
        });
    };
    return sleep(3);
    
  }
, allowOutsideClick: function() {
    return !Swal.isLoading();
  }
}).then(function(result) {
  console.log(result);
  
  if (result.value) {
    Swal.fire({
      title: '完了'
    , text:  '入力文字:' + result.value
    });
  }
});

showLoaderOnConfirmは、確認ボタンがクリックされた際にプレ実行する処理を入れるための引数。例えば入力したものに対するバリデーションや、何かの処理を入れたりしたいときに用いる。

showLoaderOnConfirmは、comfirm処理前（preconfirm処理中）に処理中アイコン（○がぐるぐる回っているローディングアイコン）を表示するための引数。デフォルトはfalseで表示されない。trueにする事でアイコンが表示される。

利用時の注意

showLoaderOnConfirmをtrueにする場合、preConfirm引数も合わせて設定する必要がある。preConfirmが無いとローダーは表示されない。

動き的には

ボタンをクリックする
preComfirmの処理が呼ばれる
comfirm処理が完了する（上記例の「}).then(function(result) {」の処理に進む）

のようになっており、2のpreComfirm処理中に確認ボタンに変わってローディングアイコンが表示される。

ローディングアイコンは、処理時間が長い場合などユーザに操作を待ってもらう場合に表示させる事で、処理が動いていることを表現することができる。allowOutsideClick・allowEscapeKeyをあわせて設定することで、処理中にユーザ側の操作でダイアログを閉じられないようにすると良い。

参考

単純にダイアログ表示時に処理中アイコンを表示したい場合、次のようにonBeforeOpenとSwal.showLoading()を使用すると良い。

過去記事SweetAlert2を使ってキレイでリッチなJavaScriptダイアログ表示を実現する方法

2019.4.9

入力フィールドの表示（input、inputPlaceholder、inputValue）

SweetAlert2の入力フィールド指定例（input/inputPlaceholder）

Swal.fire({
  title: 'タイトル'
, html : 'textを入力してください。'
, input : 'text'
, inputPlaceholder: 'プレースホルダーをここに指定'
}).then(function(result) {
  if (result.value) {
    console.log(result.value);
  }
  
  Swal.fire({
    title: 'タイトル'
  , html : 'email入力してください'
  , input : 'email'
  }).then(function(result) {
    if (result.value) {
      console.log(result.value);
    }
    
  });
  
});

inputは、入力項目を表示するための引数。規定値はnullで入力フィールドは表示されない。以下のパラメータを指定すると、それぞれに対応した入力フィールドが表示される。

text：1行のテキスト
textarea：複数行のテキスト
email：メールアドレス
password：パスワード（入力文字は●で表示される）
number：数字
tel：電話番号
range：数字（事前定義された範囲からスライドによって選択させる）
select：セレクトボックス（ドロップダウンリスト）
radio：ラジオボタン
checkbox：チェックボックス
file：ファイル指定
url：URL

ダイアログに入力させて取得したい情報の種類を元に、inputの種類を決めると良い。

inputがemailやurlなど特定の種類の場合、ボタンクリック時に自動的にエラーが表示され、指定形式で入力されないと以降の処理に進めないようになっているため便利である。 inputValidatorを指定して独自のチェックも可能。

参考：SweetAlert2のInput Types

inputPlaceholderを指定すると、入力フィールドのプレースホルダーに指定した文字列が表示される。（プレースホルダーとは、入力フィールドが未入力の場合に表示される、入力を促すための文字のこと）

inputValueを指定すると、入力フィールドに初期値を設定できる。inputValueが有効なのは、inputがtext, email, number, tel, textareaの場合のみ。

入力項目の選択肢の設定（inputOptions）

Swal.fire({
  title: 'タイトル'
, input: 'select',
  inputOptions: {
    'apples' : 'Apples',
    'bananas': 'Bananas',
    'grapes' : 'Grapes',
    'oranges': 'Oranges'
  }
, inputPlaceholder: '果物を選択してください'
, showCancelButton: true
, inputValidator: function(value){
    return new Promise(function(resolve){
      if (value === 'oranges') {
        resolve();
      } else {
        resolve('You need to select oranges :)');
      }
    });
  }
}).then(function(result) {
console.log(result);
  if (result.value) {
    Swal.fire('You selected: ' + result.value);
  }
});

inputOptionsは、入力項目のtypeがドロップダウンリスト（select）またはラジオボタン（radio）の場合に利用できる引数。規定値は{}。

HTMLタグを書かなくてもオブジェクトで{value : key}形式で記載すれば簡単に選択肢を設定可能。

入力項目の属性の設定（inputAttributes）

整理中

うまく使いたい引数（使用頻度：中）

ボタンの色設定（confirmButtonColor、cancelButtonColor）

Swal.fire({
  title: 'タイトル'
, html : '説明文'
, showCancelButton : true
, cancelButtonText : 'やめる'
, confirmButtonColor : '#008080'
, cancelButtonColor : '#ffa500'
}).then(function(result) {
  console.log(result);
});

confirmButtonColorでは確認ボタンの色を、cancelButtonColorではキャンセルボタンの色を設定する事が可能。デフォルトではそれぞれ青色・グレー。

SweetAlert2を利用するサイトのカラーに合わせてボタン色を変更すると良い。

ボタン位置の反転表示設定（reverseButtons）

Swal.fire({
  title: 'タイトル'
, html : '説明文'
, showCancelButton : true
, cancelButtonText : 'やめる'
, reverseButtons : true
}).then(function(result) {
  console.log(result);
});

reverseButtonsを利用する事で、確認ボタンとキャンセルボタンの位置を逆転する事が可能。

デフォルト（true）：確認ボタンが左、キャンセルボタンが右
反転した場合（false）：確認ボタンが右、キャンセルボタンが左

個人的には確認ボタンは右にあったほうが馴染むため、reverseButtonsでボタン位置を逆転させている。ユーザビリティによって設定をすればよい。

閉じるボタンの表示設定（showCloseButton）

Swal.fire({
  title: 'タイトル'
, html : '説明文'
, showCancelButton : true
, cancelButtonText : 'やめる'
, showCloseButton : true
}).then(function(result) {
  console.log(result);
});

showCloseButtonをtrueにする事で、ダイアログに閉じるボタン（×ボタン）を表示する事が可能。デフォルトはfalseで、閉じるボタンは表示されない。

キャンセルボタンを表示しているのであれば閉じるボタンの表示は不要であるため、使いどころは限定的。キャンセルボタンではなく閉じるボタンにて処理をキャンセルさせるような場合に使用する。

ダイアログに画像を表示する（imageUrl、imageWidth、imageHeight、imageAlt）

Swal.fire({
  title: 'Sweet!',
  text: 'Modal with a custom image.',
  imageUrl: 'https://unsplash.it/400/200',
  imageWidth: 400,
  imageHeight: 200,
  imageAlt: 'Custom image',
  animation: false
})

imageUrlは、画像のURLを指定するための引数。

imageWidth・imageHeightは、それぞれ画像の幅と高さを指定するための引数。

imageAltは、画像への代替文字を指定するための引数。

URLと幅・高さを指定すれば簡単にダイアログ内に画像を表示させる事が可能。SweetAlert2に用意されているアイコン（type）の代わりなどに使用してもよいと思われる。

入力項目へのバリデーションの設定（inputValidator）

整理中

入力項目のバリデーションメッセージの設定（validationMesage）

整理中

フッターの表示（footer）

整理中

ダイアログ表示位置の設定（position）

Swal.fire({
  title: 'タイトル'
, html : 'descriptionはタイトルの横に表示される'
, type : 'success'
, position : 'bottom'
});

positionは、ダイアログの表示位置を指定するための引数。次のパラメータを指定可能。（デフォルトは'center'で画面中央表示）

'top'：画面上部中央
'top-start'：画面左上
'top-end' ：画面右上
'center'：画面中央
'center-start'：画面中央左
'center-end'：画面中央右
'bottom'：画面下部中央
'bottom-start'：画面左下
'bottom-end'：画面右下

通常ダイアログとして利用する場合はデフォルトで問題ないと思われるが、toastで表示する場合は位置を端に寄せたほうが見やすいと思われる。

トースト形式での表示（toast）

Swal.fire({
  title: 'タイトル'
, html : 'descriptionはタイトルの横に表示される'
, type : 'success'
, toast: true
, position: 'top-end'   //画面右上
, showConfirmButton: false
, timer: 3000           //3秒経過後に閉じる
});

toastは、トースト形式でダイアログを表示したい場合に設定する引数。

※トーストとは、画面の端にポッと出てしばらくすると消えるような通知を指す。

トーストとは、主にデスクトップアプリケーションの機能で、情報通知用の小さなウィンドウをディスプレイの下方から一時的にポップアップ表示することである。
例えば電子メールを新たに受信した場合や、ファイルのダウンロードが完了した場合、インスタントメッセンジャーで仲間がログインした場合、などが想定される。
トーストは画面の端に小さく現れ、一定時間が過ぎると自動的に引っ込むようになっている。トースト上の通知を確認し、それが今すぐ行動する必要のない情報であれば、無視することもできる。内容をすぐに確認したい場合は、トーストで表示されたウィンドウをクリックすれば、通知の内容に直接アクセスでき、また、無視して目下の作業を妨げられずにやり過ごすこともできる、という利点がある。
IT用語辞典より引用

規定値はfalseでtoast表示はされない。trueを指定するとtoast形式でダイアログが表示される。

通常toastを利用する場合、表示位置を指定するpositionや、指定時間経過後に自動的に閉じる設定をするtimerと一緒に利用する。（上記サンプルを参照）

toastを利用する場合を考えると、titleとtext（またはhtml）は両方指定せず、どちらかのみを使用したほうが表示がスッキリする。

ダイアログ幅の設定（width)

Swal.fire({
  title: 'タイトル'
, html : 'descriptionはタイトルの横に表示される'
, type : 'success'
, width : '64rem'
});

widthは、ダイアログの幅を設定するための引数。px、%、remで指定する。デフォルトは32rem。

デフォルトの幅だと思ったとおりに改行してくれずにダイアログが縦長になるケースがあるため、そのような場合にwidthを使用すると良い。

ダイアログの余白の設定（padding）

Swal.fire({
  title: 'タイトル'
, html : 'descriptionはタイトルの横に表示される'
, type : 'success'
, padding : '6rem'
});

paddingはダイアログの余白（paddin）を設定するための引数。デフォルトは1.25rem。

どうしてもデフォルトの余白では気に入らない場合はpaddingを設定すると良い。

ダイアログをWindowサイズで表示する設定（grow）

Swal.fire({
  title: 'タイトル'
, html : 'descriptionはタイトルの横に表示される'
, type : 'success'
, grow : 'row'
});

growはダイアログの幅または高さをブラウザのWindowサイズで表示したい場合に設定する引数。ブラウザの幅・高さを変えると、それに合わせてダイアログの大きさも変わる。

次のパラメータを指定可能。

'row'：幅をWindowサイズで表示
'column'：高さをWindowサイズで表示
'fullscreen'：幅と高さをWindowサイズで表示
false：デフォルト

使いどころは限られてくるが、widthで幅調整をするのがめんどくさいような場合はrowを設定して常にWindowsサイズで表示させておくのも手。大きな画像や動画を表示させたい場合はfullscreenが便利。また、positionと組み合わせて使うと面白いと思われる。

あまり使わないけれど覚えておきたい引数（使用頻度：低）

ダイアログへのCSSの設定（customClass）

customClassはダイアログに対して特定のCSSを適用したい場合に使用する引数。

上級者向け。SweetAlert2デフォルトのCSSでは満足できない場合に利用する。

ダイアログ背景の設定（background）

Swal.fire({
  title: 'タイトル'
, html : 'descriptionはタイトルの横に表示される'
, type : 'success'
, background : '#FFFF00'
});

backgroundはダイアログの背景を設定したい場合に使用する引数。デフォルトは'#fff'。

ダイアログの背景色を変えて目立たせたい場合にこの引数を使うと良いが、背景色を変えるとボタンやテキストの色も合わせて変更する必要が出てくるため、基本的にはデフォルトのままでよいと思われる。

ダイアログ枠外背景の設定（backdrop）

Swal.fire({
  title: 'タイトルをここに設定'
, html : 'descriptionをここに設定。'
, type : 'info'
, backdrop : `
    rgba(0,0,123,0.4)
  `
});

backdropはダイアログ枠外の背景を設定するための引数。true・false以外に、背景設定用のCSS（背景色や画像等）の指定が可能。

規定値はfalse。ダイアログ表示時に枠外はグレー表示となりダイアログ以外の部分は操作できない。
trueを設定する事で、ダイアログ以外の部分の表示はそのまま（グレー表示とならない）となり、ダイアログ枠外のクリック操作等が行える。また、枠外をクリックした際にダイアログが閉じられなくなる（allowOutsideClickがfalseに自動的になる様子）。
CSSを設定する事で自由に枠外の装飾が可能。例えば、枠外を青色に表示したり、画像を入れたりといった事が可能。

基本的にはデフォルト設定でよいと思われるが、枠外をもっと暗くしたいなどの場合は利用すると良い。

ボタンへのフォーカス設定（focusConfirm、focusCancel）

focusConfirm、focusCancelは、ボタンへのデフォルトのフォーカス設定をするための引数。

forcuConfirmは確認ボタンへのフォーカス設定を行うもので、デフォルトはtrue。
focusCancelはキャンセルボタンへのフォーカス設定を行うもので、デフォルトはfalse。

設定を試して動作確認をしてみたが、ダイアログ表示時にボタンにカーソルが設定されるような動きにはならず、想定とは異なっていた。そのため、使いどころは分からない。

入力テキストの自動空白除去設定（inputAutoTrim）

inputAutoTrimは、入力した文字列の両端の空白を自動的にトリムするための引数。デフォルトはtrueでトリムされる。

意図的に空白を除去したくないような場合は、falseを設定すればよい。

ボタンのaria-label設定（confirmButtonAriaLabel、cancelButtonAriaLabel、closeButtonAriaLabel）

confirmButtonAriaLabel、cancelButtonAriaLabel、closeButtonAriaLabelを利用する事で、ボタンにaria-labelを設定する事が可能。

aria-labelとは画像や文字に情報を付けたいときに利用する情報。目の不自由な方のためのスクリーンリーダーというものが読み上げられるようになるため、余裕があれば設定しておきたい。

全く使わない引数（使用頻度：ほぼ0）

ターゲットの指定（target）

targetはダイアログを表示するターゲット要素を指定するための引数。規定値は'body'。ダイアログを表示したいコンテナー要素を指定するが、通常使う場合は規定値のままで特に気にしなくてよい。

アニメーションの指定（animation）

Swal.fire({
  title: 'タイトル'
, html : 'descriptionはタイトルの横に表示される'
, type : 'success'
, animation : false
});

animationはアニメーションを指定するための引数。デフォルトはtrue。

動きのあるダイアログがSweetAlert2の魅力のため、意図的にfalseを使うケースは無いと想定される。

ダイアログの高さの自動設定（heightAuto）

heightAutoは意図的に高さを変えたい場合に指定する引数。デフォルトはtrue。

SweetAlert2を使いたい場面においてダイアログの高さが気に入らないような場合はここをfalseにして高さを指定すると良いが、基本的には使わないと想定される。

Enterキーの許可設定（allowEnterKey）

allowEnterKeyはEnterキーを無効にする引数。・・・と思って試してみたが、意図した動きにならず、使い方がよく分からない。

stopKeydownPropagation、keydownListenerCapture

使いどころがよく分からない。