Angular フォームライブラリ | ng-hub-ui-forms

アクセシブルな Angular フォームフィールド(input、textarea、slider、select、datepicker)。コントロール/グループ/フォーム単位のエラーを自動表示し、リアクティブフォームと CSS 変数に対応します。

API リファレンス

forms の完全な仕様をここにまとめました。バインド、リッスン、プロジェクション、テーマ設定ができるすべてが一か所に集約されています。必要なものを接続し、好きなようにスタイリングしてください — standalone で signal フレンドリーです。

インプット

87 個のインプットで forms を調整。通常の Angular @Input と同じようにバインドできます。

名前デフォルト説明
formControlName / [formControl]string | FormControl任意のフィールドをリアクティブコントロールにバインドします。コントロールが touched かつ無効な場合、エラーが自動的に表示されます。
labelstring''フィールドのラベルテキスト。
labelType (hub-input, hub-select, hub-datepicker)'stacked' | 'floating' | 'horizontal''stacked'ラベルの配置。`floating` はラベルをコントロールの内側に配置し、フィールドがフォーカスされるか値を持つまで、プレースホルダーの代わりを務めます。
labelType (hub-textarea, hub-otp-input, hub-slider, hub-segmented, hub-timepicker)'stacked' | 'horizontal''stacked'ラベルの配置。これらのフィールドに `floating` のバリアントはありません。`floating` を渡しても、stacked のラベルを描画します。
placeholder (hub-input, hub-select, hub-textarea, hub-datepicker)string'' / NgSelectConfig.placeholder (hub-select)プレースホルダーテキスト。
formTextstringコントロールの下に表示されるヘルパーテキスト。
type (hub-input) — file is deprecated'text' | 'number' | 'password' | 'email' | 'tel' | 'url' | 'color' | 'checkbox' | 'switch' | 'counter' | 'file''text'hub-input のフォーマット。
passwordRevealed (hub-input)booleanfalseパスワードフィールドの表示状態を表す双方向モデル。目のアイコンをクリックすると更新され、値を設定すると表示または非表示になります。
passwordToggle (hub-input)booleantrueパスワードフィールドに統合された表示切り替えボタンをレンダリングするかどうか。
hideOnBlur (hub-input)booleantrueフィールドからフォーカスが外れたときに、表示中のパスワードを自動的に再度マスクするかどうか。
capsLockWarning (hub-input)booleantrueCaps Lock が有効な間、フィールドの下にヒントを表示するかどうか。
passwordStrength (hub-input)booleanfalseフィールドの下にオプションの4セグメント強度メーターを表示します。スコアリングは provideHubForms で上書きできます。
autocomplete (hub-input)string''ネイティブの autocomplete 属性。パスワードマネージャー向けに current-password や new-password などを指定します。
clearable (hub-input)booleanfalsetrue の場合、値が入ると内部に ✕ ボタンを表示します。コントロールをクリアし、空の検索語を発行します。
debounceTime (hub-input)number0search イベントが発火するまでのデバウンス時間(ミリ秒、0 はキー入力ごと)。
mask (hub-input)stringテキストフォーマット用のパターンマスク。トークン: 0 = 数字、A = 英字、* = 英数字。その他の文字はリテラルな区切り文字です。例: "0000 0000 0000 0000"。
unmaskValue (hub-input)booleanfalseマスクを設定した場合、フォーマット済みテキストの代わりに、入力された生の文字(区切り文字なし)をフォームに保存します。
range (hub-slider)booleanfalse2 つのつまみを持つレンジスライダー。値は [lower, upper] のタプルになります。
options (hub-segmented)HubSegmentedOption[][]hub-segmented の選択可能なオプションを、レンダリング順に指定します — それぞれ { value, label, disabled? } です。
size (hub-segmented)'sm' | 'md' | 'lg''md'セグメンテッドコントロールの視覚的な密度:'sm'、'md'(デフォルト)または 'lg'。
disabled (all fields)boolean (two-way, model)falseフィールドを無効化します。共通の基底クラスからすべてのフィールドが継承しており、双方向です — リアクティブコントロール経由で無効化されたフィールドは、その変化を返します。`hub-segmented` では、個々のオプションも `option.disabled` を通じて個別に除外できます。
multiple (hub-segmented)booleanfalse複数選択を許可します。値は配列になり、オプションは aria-pressed でトグルします。
vertical (hub-segmented)booleanfalseセグメントを横一列ではなく縦に積み重ねます。
vertical (hub-select) — deprecatedbooleanfalse非推奨であり、同じく非推奨の dropdown 以外のフォーマットに紐づいています。buttons/checkbox/radio のオプションを縦方向に並べます。`<hub-segmented [vertical]="true">` を使ってください。
color (hub-segmented)'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'neutral' | string''選択セグメントのセマンティックアクセント(primary, success, …)または任意の色。single モードでスライドします。
value (hub-segmented)unknown | unknown[]undefined双方向バインド可能な選択値(model()):single モードでは選択されたオプションの値、multiple モードでは選択値の配列になります。valueChange を発行します。通常は代わりに formControlName を通じて制御します。
format (hub-select) — deprecated for buttons/checkbox/radio'dropdown' | 'buttons' | 'checkbox' | 'radio''dropdown'select が同じ値をどのようにレンダリングするか。
prepend / append (hub-input, hub-select, hub-textarea, hub-datepicker, hub-timepicker)string | string[]''ボックスとして描画されるあらゆるフィールドに付く静的なグループアドオン。文字列は 1 つのアドオン、配列はその連なりを表し、空の項目は空のボックスとして描かれず破棄されます。アドオンはフィールドの境界線を共有し、フォーカスできません。縁に付く操作可能なコントロールが必要な場合は [hubPrepend] / [hubAppend] テンプレートを使ってください。両方を同時に指定でき、投影されたコンテンツは常にその側の最も外側の要素になります。
items / bindLabel / bindValue / multiple (hub-select)any[] / string / string / boolean選択肢、オブジェクト項目の label/value プロパティ名、および複数選択。
groupBy (hub-select)string | undefinedundefinedドロップダウン項目をオプショングループのヘッダーの下にグループ化するために使用されるプロパティ名(ドットパス)。
searchable / clearable (hub-select)booleantrue入力によってオプションを絞り込めるか(searchable)、および組み込みのクリアボタンで選択を解除できるか(clearable)。どちらもデフォルトは true です。
closeOnSelect (hub-select)booleantrue項目を選択した後にドロップダウンを閉じるかどうか。multiple モードで複数の値を選ぶ間開いたままにするには false を設定します。
fixedPlaceholder (hub-select)booleanfalse値が選択されてもプレースホルダーを表示したままにします。デフォルトは false(選択時にプレースホルダーが隠れる)で、ng-select v23 の慣例に反するデフォルトを反転させています。
loading / notFoundText (hub-select)boolean / stringfalse / NgSelectConfig.notFoundTextloading は非同期の項目を取得している間、ドロップダウンのローディング状態を表示します。notFoundText は検索語に一致する項目がないときに表示されるメッセージです。
readonly (hub-input, hub-select, hub-textarea, hub-datepicker, hub-otp-input, hub-timepicker)booleanfalsetrue の場合、フィールドは値を表示しつつ一切の操作を受け付けません。disabled のスタイルやフォーム状態の変更は伴いません。
appendTo (hub-select)string | undefined'body'ドロップダウンパネルを追加する先の要素の CSS セレクタ。デフォルトは 'body' で、パネルが overflow/transform を持つ祖先(カード、スクロールコンテナ、モーダル)から抜け出せるようにします。インラインでレンダリングするには undefined を渡します。
addTag (hub-select)boolean | ((term: string) => any | Promise<any>)false検索語から項目を作成します(dropdown フォーマット):true は検索語をそのまま追加し、関数は検索語を新しい項目にマッピングします(同期または Promise)。
addTagText (hub-select)stringNgSelectConfig.addTagTextaddTag が有効なとき、入力中に表示される「項目を追加」行のラベル。
minTermLength (hub-select)number0フィルタリング(または typeahead の Subject)が動き出すまでの検索語の最小長。
typeahead (hub-select)Subject<string> | undefinedundefined非同期/サーバーサイド読み込みのために検索語の変更を受け取る Subject。指定するとクライアントサイドのフィルタリングは無効になります — 結果は items を通じて返してください。
compareWith (hub-select)((a: any, b: any) => boolean) | undefinedundefined項目とバインドされた値のカスタム等価判定(例:オブジェクトを id で比較)。省略時はベンダー組み込みの比較が適用されます。
searchFn (hub-select)((term: string, item: any) => boolean) | undefinedundefined`searchable` が使う組み込みのマッチング処理を置き換えます。入力された検索語と項目を受け取り、その項目が一致するかどうかを返します — これにより、ラベルに表示されていないフィールドまで検索の対象にできます。
mode (hub-datepicker)'single' | 'range' | 'day-time-range''single'単一の日付、自由な日付範囲、または 1 日の中での開始時刻と終了時刻。
granularity (hub-datepicker)'year' | 'month' | 'day' | 'hour' | 'minute' | 'second''day'選択された各時点が持つ精度と、それを選ぶパネルを決めます。year と month は 12 セルのグリッド、day はカレンダーを表示し、hour・minute・second はそこに時刻入力を追加します。mode とは直交する軸で、mode は選ぶ点の数を、granularity は各点の精度を決めます。既定は day で、従来どおり YYYY-MM-DD の文字列を出力します。hour 以降では、閲覧者のローカル時刻とその日付のオフセットを含む完全な ISO 8601 タイムスタンプになります。
valueFormat / parse (hub-datepicker)'iso' | 'date' | 'timestamp' | ((date) => unknown) / ((raw) => Date | null) | null'iso' / null値に関する軸です。valueFormat はバインドされたコントロールが保持する形を決めます: 'iso'(既定)、ネイティブな Date なら 'date'、エポックミリ秒なら 'timestamp'、それ以外は関数を渡します。parse は入力値の読み取り方を決め、任意の桁数の ISO 文字列・Date インスタンス・エポックミリ秒の自動判定を置き換えます。min と max にも適用されます。
minuteStep / secondStep / hourFormat (hub-datepicker)number / number / '12' | '24' | undefined5 / 1 / undefined時刻まわりの設定です。minuteStep と secondStep はスピンボタンの増分、hourFormat は 12 時間制か 24 時間制を強制します。未指定ならロケールから導出され、パネルだけでなく入力欄の表示にも適用されるため、両者が食い違うことはありません。3 つとも provideHubForms のグローバル設定にフォールバックします。
min / max / disabledDates (hub-datepicker)string | Date | number | null / ((date: Date) => boolean) | nullnull選択可能な範囲と、日付ごとの無効化述語です。範囲は日単位ではなく時刻まで考慮します。その日のどの瞬間も許可されない場合にのみ日が無効になるため、min = 2026-09-01T14:00 では 9 月 1 日はクリック可能なままで、それより早い時刻は時刻コントロールが拒否します。ISO 文字列、Date、エポックミリ秒を受け取ります。
locale / firstDayOfWeek / weekdayFormat (hub-datepicker)string / number / 'short' | 'narrow' | 'long'LOCALE_ID / undefined / undefinedカレンダーの i18n:locale は表示値と月/曜日名に使う BCP-47 タグです(デフォルトはアプリの LOCALE_ID、なければ en-US)。firstDayOfWeek は週の最初の曜日を設定します(0 = 日曜、1 = 月曜…)。weekdayFormat は曜日ヘッダーの表示幅を選びます。後の 2 つはグローバルな provideHubForms 設定にフォールバックします。
displayFormat / timeDisplayFormat / rangeSeparator / labels (hub-datepicker)Intl.DateTimeFormatOptions | string | ((date) => string) / Intl.DateTimeFormatOptions / string / Partial<HubDatepickerLabels>undefined / undefined / undefined / {}表示の書式です。displayFormat は選択された値を描画し、Intl.DateTimeFormatOptions、'dd/MM/yyyy HH:mm' のような Angular の日付パターン、または関数を受け取ります。粒度が時刻を含むようになると timeDisplayFormat がその上に合成されるため、日付部分は displayFormat が指定したままに保たれます。rangeSeparator は範囲の 2 つの日付のあいだに入るテキスト、labels はインスタンスごとに UI ラベルを上書きします(グローバル設定の上にマージされます)。
clearable / showToday / closeOnSelect (hub-datepicker)booleantrue / true / true動作フラグ:clearable はクリアのショートカットを表示し、showToday は「今日」ショートカットを表示し、closeOnSelect は日付を選択した後にカレンダーを閉じます(single モードのみ)。デフォルト: true / true / true。
multiple (hub-file-input)booleanfalse複数のファイルを保持できるかどうか。コントロールの値を File から File[] に切り替えます。
accept (hub-file-input)string'*'許可するファイル種別(例: image/*,.pdf)。OS のダイアログだけでなく、ドロップや貼り付けにも適用されます。
maxSize / minSize / maxTotalSize (hub-file-input)number | nullnullファイルごとの最大・最小サイズと、合計の最大サイズ(バイト)。
maxFiles (hub-file-input)number | nullnullファイル数の上限。multiple と併用する場合にのみ意味を持ちます。
dragDrop / paste (hub-file-input)booleantrueフィールドにファイルをドロップできるか、また貼り付けられるか。
preview (hub-file-input)'none' | 'list' | 'grid''list'ファイルの表示方法: 表示しない、リスト、サムネイルのグリッド。
allowDuplicates (hub-file-input)booleanfalse同じファイルを二度選択できるかどうか(名前・サイズ・更新日時をキーとします)。
capture (hub-file-input)'user' | 'environment' | nullnull対応プラットフォームで、ファイルブラウザーではなく端末のカメラを開きます。
autoUpload (hub-file-input)booleantrue受理されたファイルを直ちにアップロードするかどうか。アップローダー未登録なら無視されます。
buttonLabel / hint (hub-file-input)string | nullnull参照ボタンのテキストと、自動生成される制約のヒントを上書きします。
dropText / dropSubtext (hub-file-input)string | nullnullドロップゾーンの 2 行の案内文をインスタンス単位で上書きします。どちらも既定ではグローバルなラベルを使います。
classlist (every field except hub-segmented and hub-legend)string''ホスト要素に適用する追加の CSS クラス。
showValid (all fields)booleanHubFormsConfig.showValid有効なフィールドが有効状態を表示するかどうか。未操作のフィールドまで残らず緑に塗るフォームは何も伝えないため、デフォルトではオフです。無効状態のほうは常に表示されます。
validFeedback (all fields)string | nullnull`showValid` が有効なとき、フィールドが有効になった時点でその下に表示されるメッセージ。
invalidFeedbackTemplateFn (all fields)((key: string, value: any) => string) | nullnull特定のエラーキーに対するメッセージを、このフィールドに限って上書きします。エラーキーとその値を受け取り、表示するテキストを返します — アプリ全体のデフォルトは `provideHubForms` にあります。
min / max (hub-input)number | undefined (two-way, model)undefinednumber および counter フォーマットにおける数値の下限・上限。双方向であるため、自身の値をクランプするカウンターは、その境界値を呼び出し元に返します。
mode (hub-otp-input)'numeric' | 'alphanumeric' | 'alpha''numeric'各ボックスが受け付ける文字と、スマートフォンで表示されるキーボードの種類:数字のみか、英字と数字か。
min / max (hub-timepicker)string (HH:MM)''フィールドが受け付ける最も早い時刻と最も遅い時刻を `HH:MM` で指定します。空の場合は制限なしです。
step (hub-timepicker)number (seconds)0ネイティブのステッパーの刻み幅(秒単位)。`0` の場合はブラウザーのデフォルトである 1 分のままになります。
group / groupName (form[hubForm], hub-fieldset)AbstractControl | null / string | undefinednull / undefinedコンテナがエラーを表示する対象のグループ。`group` には `AbstractControl` を直接渡すか、`groupName` には囲んでいるフォームの子コントロールの名前を渡します — コンテナがすでに対象のグループを囲んでいる場合は、どちらも不要です。
errorTrigger (form[hubForm], hub-fieldset)'touched' | 'submit' | 'always''touched'グループレベルのエラーが表示されるタイミング:グループが touched になった時点か、送信が試みられた後のみか、直ちに表示するか。
formTextType (all fields)'bottom'補助テキストの配置。`bottom` のみ対応します。
rows (hub-textarea)number表示するテキストの行数。
cols (hub-textarea)number表示する列数。指定するとテキストエリアは全幅への伸張をやめます。
maxlength (hub-textarea)number最大文字数。ネイティブの制限とカウンターの両方を決めます。
counter (hub-textarea)booleanコントロールの下に文字数カウンターを表示するかどうか。
autoresize (hub-textarea)booleanテキストエリアが内容に合わせて広がるかどうか。
length (hub-otp-input)numberコードのセル数(文字数)。
secret (hub-otp-input)booleanパスワードのように文字を伏せます。
separator (hub-otp-input)stringグループ間に表示する区切り文字。
separatorEvery (hub-otp-input)numberN セルごとに視覚的な区切りを挿入します(0 は挿入しない)。
showValue (hub-slider)booleanつまみの上に値のバブルを表示するかどうか。
step (hub-input, hub-slider)numberステップ値(数値入力・カウンター入力)。
legend (hub-fieldset)string凡例のテキスト。`hubLegend` テンプレートを投影した場合は無視されます。
required (all fields)boolean | null (two-way, model)nullフィールドが必須かどうか。リアクティブなバインディングでは、コントロール自身のバリデーターから導出されるため、テンプレート上で直接指定した値が尊重されるのはテンプレート駆動のフィールドのみです。この値がアスタリスクと `required` 属性を制御します。
required (hub-legend)boolean必須インジケーターを表示するかどうか。
invalid (hub-legend)boolean無効状態のスタイルを適用するかどうか。

アウトプット

forms の動作に反応 — ロジックを接続できる 13 個のイベント。

名前説明
valueChangeEventEmitter<value>フィールドの値が変化するたびに発行されます。
search (hub-input)EventEmitter<string>入力中に発行されるデバウンス済みのタイプアヘッド語(テキスト系入力)。
rejected (hub-file-input)EventEmitter<HubFileRejection[]>宣言された制約により拒否されたファイルと、それぞれの拒否理由。
fileRemoved (hub-file-input)EventEmitter<File>選択から削除されたファイル。
uploadStateChange (hub-file-input)EventEmitter<readonly HubFileItem[]>アップロードの状態または進捗が変わるたびの、項目の全リスト。
submit (form[hubForm]) — the native eventSubmitEvent (native, not a custom output)カスタム出力ではありません。`hubForm` はフォーム自身の `submit` イベントを購読し、デフォルトの画面遷移を抑止し、ツリーを touched としてマークして、submitted の状態を切り替えます。独自のハンドラーはフォームの `(submit)` にバインドしてください。
disabledChange / requiredChange (all fields) · labelTypeChange / placeholderChange / minChange / maxChange / passwordRevealedChange (hub-input) · valueChange (hub-segmented)EventEmitter<T> (the paired half of each two-way model)双方向の `model()` 入力はいずれも対応する `Change` 出力を公開しており、そのおかげで `[(disabled)]` などが機能します。バナナ・イン・ア・ボックス構文ではそれらが見えないため、ここに記載しています。
opened / closed / cleared / viewChange (hub-datepicker)EventEmitterカレンダーのライフサイクルおよびナビゲーションイベント。
onOpen / onClose / onClear / onSearch / onAdd / onRemove (hub-select)EventEmitterドロップダウンのライフサイクルおよびタグ/タイプアヘッドイベント。
onFocus / onBlur (hub-select)EventEmitter<any>ドロップダウンコントロールがフォーカスを得たり失ったりしたときに発行されます(dropdown フォーマット)。ベンダーの focus/blur イベントを中継します。
scroll / scrollToEnd (hub-select)EventEmitter<{ start: number; end: number }> / EventEmitter<any>scroll はドロップダウンリストのスクロール中に可視範囲の { start, end } ウィンドウを発行し、scrollToEnd はリストが末尾に達したときに発行されます — typeahead と組み合わせた無限/ページング読み込みのフックです。
enter (hub-input)EventEmitter<number | string | boolean | File | FileList | null>Enter キーが押されたときに現在の値を発行します。
completed (hub-otp-input)EventEmitter<string>すべてのセルが埋まると完全なコードを発行します。

テンプレート

自分好みに — 10 個のテンプレートスロットでカスタムマークアップをプロジェクションできます。

名前説明サンプル
hubFormTextリッチなヘルパーテキストコンテンツを投影します。<ng-template hubFormText>…</ng-template>
hubValidationError指定されたエラーキーのメッセージを上書きします。<ng-template hubValidationError key="min">…</ng-template>
hubLegendカスタムの fieldset legend コンテンツ。<ng-template hubLegend>…</ng-template>
ng-option-tmp (hub-select)カスタムのドロップダウンオプションのレンダリング(再エクスポートされた ng-select ディレクティブ)。<ng-template ng-option-tmp let-item="item">…</ng-template>
hubFileIcon (hub-file-input)サムネイルのないファイル用のアイコン。項目を暗黙のコンテキストとして受け取ります。<ng-template hubFileIcon let-item>…</ng-template>
hubFilePreview (hub-file-input)選択されたファイルの描画全体を置き換えます。項目に加えて、削除・再試行・キャンセルの各アクションを受け取ります。<ng-template hubFilePreview let-item let-remove="remove">…</ng-template>
hubFileDropzoneNotice (hub-file-input)ドロップゾーンの最上部、アイコンの上に任意のマークアップを投影します。案内文にも制約のヒントにも表せない通知のための場所です。<p hubFileDropzoneNotice>2 documents still missing</p>
hubSegmentedOption (hub-segmented)各セグメントの内容(アイコン、バッジ、リッチなマークアップ)を置き換えます。選択、キーボードナビゲーション、ARIA は引き続きコンポーネントが管理します。コンテキスト:選択肢(暗黙)、selected、index。<ng-template hubSegmentedOption let-option let-selected="selected" let-index="index">…</ng-template>
hubSelectSuffix (hub-select、非推奨)22.16.0 で非推奨 — すべてのフィールドで同じことができる [hubAppend] を使ってください。引き続き動作しますが、両方ある場合は [hubAppend] が優先されます。セレクトの行末側の端に操作可能なコントロールを付けます。選択中の項目に対して働くボタン — 設定する、参照する、新規作成するといった用途です。投影コンテンツではなくテンプレートとして宣言するのは、セレクトの総取り ng-content が ng-option をエンジンへ渡す役目を持ち、そのまま飲み込んでしまうためです。テンプレートから描画することで DOM 上でもアクションがコントロールの後に残るため、タブ移動は先にフィールドへ到達します。コントロールとアクションは境界線を共有し、ひとつのフィールドとして読めます。<ng-template hubSelectSuffix><button …>…</button></ng-template>
hubPrepend / hubAppend (all box-shaped fields)フィールドの端に付ける、prepend / append の文字列では運べない内容 — アイコンや、値に対して働くボタンです。値を持つ箱として描かれるすべてのフィールド(hub-input、hub-select、hub-textarea、hub-datepicker)で使えます。文字列アドオンを置き換えるのではなく組み合わせます。文字列が先に描画されるため、投影された内容は常にその側の最も外側になります — 単位がフィールドを説明し、アクションはその外側に置かれます。投影された要素は自身のものではなくフィールドの境界線・角丸・高さをまといます。そのためボタンがコントロールの横に二重の太い継ぎ目を描くことはありません。フィールドの ng-content はすでに別用途で使われているため、テンプレートとして宣言します。 スロットには別のフィールド(hub-input、hub-select、hub-textarea、hub-datepicker を直接の子として)も渡せます。ホストのフィールドとぴったり接するため、価格とその期間が本来ひとつである記述として読めます。<ng-template hubAppend><button …><hub-icon … /></button></ng-template>