hb-input-file

Category: inputs · Tags: inputs

hb-input-file is a file-upload control for HTML Bricks forms and standalone pages. It wraps a native <input type="file"> in a Bulma-styled field, supports restricting file types with accept, optional image-placeholder mode, built-in English and Italian UI strings, and reports its value with a setVal custom event.

Overview

• Standard layout — Bulma file has-name is-fullwidth: “choose file” call-to-action, optional clear control (does not reopen the file dialog; click is stopped on the button), and a filename strip with a Bootstrap Icons glyph inferred from MIME type or file extension.
• Placeholder image layout — When schemaentry.params.placeHolderImage.src is set, the host shows a clickable image and translated “select image” text. The real file input stays in the shadow tree (visually hidden) but remains focusable and programmatically usable.
• Preview — After a file is chosen, the component can show an image preview (object URL) for common image types, or a MIME-style icon row for other types.
• Overlay preview — If accept looks image-oriented (the implementation treats it as such when /image/i matches accept) and the picked file is JPEG, PNG, GIF, or SVG, a compact overlay preview is used with filename and clear control.
• Validation — required means a file must be selected. Toggle show_validation to surface validationTip in a Bulma help is-danger block when the field is invalid.

Icons use the Bootstrap Icons font; the component loads the stylesheet from jsDelivr inside the shadow scope.

Custom element

| Name | Tag | | --- | --- | | hb-input-file | <hb-input-file …></hb-input-file> |

Published package name (npm): @htmlbricks/hb-input-file.

Attributes (snake_case)

Web component attributes are strings. Pass booleans as yes / no, numbers as strings where applicable, and structured data as JSON strings (for schemaentry).

| Attribute | Required | Description | |-----------|----------|-------------| | schemaentry | Yes | JSON string describing the field (see below). Invalid or unparsable JSON yields no rendered field. | | show_validation | No | yes or no (default no). When yes, shows validationTip if the field is required and no valid file is selected. | | i18nlang | No | BCP-47 style language code for built-in strings. Supported in this component: en (default behavior), it. Parent hb-form can forward its locale. | | id | No | Optional id on the host element. | | style | No | Optional inline styles on the host element. |

schemaentry (JSON)

schemaentry follows the shared form row shape (FormSchemaEntryShared) with file-specific params. At minimum you should supply id (string). Typical keys:

| Key | Type | Description | |-----|------|-------------| | id | string | Field id; forwarded on setVal and applied to the native file input. | | label | string | Optional; used by surrounding forms for labeling (this component’s markup focuses on the control). | | required | boolean | If true, a file must be chosen for valid to be true. | | validationTip | string | Message shown when show_validation is yes and the field is invalid. | | placeholder | string | Passed to the native input as placeholder where relevant. | | readonly | boolean | Forwarded to the native input. | | disabled | boolean | Disables the input and interactive controls. | | params | object | Optional InputFileParams (see next table). |

params (InputFileParams)

| Key | Type | Description | |-----|------|-------------| | accept | string | Native accept attribute: comma-separated MIME types, extensions (e.g. .pdf), or a mix. If omitted, the component uses * (any file). | | placeHolderImage | object | Enables placeholder-image mode. src (string, required) is the placeholder image URL. Optional width and height (numbers) constrain preview / placeholder dimensions (defaults used in CSS if omitted). |

Events

| Event | detail | When | |-------|----------|------| | setVal | { value: string \| undefined; valid: boolean; id: string } | Whenever value, valid, or id changes; duplicate payloads are suppressed internally. |

Listen with addEventListener("setVal", …) or the equivalent in your framework.

Internationalization

Built-in UI strings (e.g. “Choose file”, “No file selected”, clear button labels, placeholder mode copy) come from the component dictionary. Set i18nlang to switch language; it enables Italian strings, en (or omitting the attribute) keeps English.

Styling

The shadow root uses Bulma form patterns and shared tokens. Prefer Bulma CSS variables on :host — see Bulma CSS variables.

| CSS variable | Role | |--------------|------| | --bulma-text | Label, filename strip, and CTA text. | | --bulma-border | File control border (file / has-name). | | --bulma-danger | Required-empty state and danger help text. | | --bulma-link | Primary “choose file” background in standard mode. | | --bulma-scheme-main | Filename strip and placeholder surfaces. |

Additional layout and icon rules live in styles/webcomponent.scss.

CSS ::part API

| Part | Description | |------|-------------| | input | Native <input type="file"> (visually hidden in placeholder-image mode; still part-targetable). | | file-name | Filename text, or the “no file selected” hint in standard mode; in placeholder modes, the name strip / overlay filename. | | clear | Clear control in standard mode (between CTA and filename). | | invalid-feedback | The p.help.is-danger node when validation messaging is visible. |

Slots

None (htmlSlots is empty for this package).

TypeScript

Authoring types for consumers and wrappers live in types/webcomponent.type.d.ts:

• InputFilePlaceholderImage, InputFileParams
• FormSchemaEntry (file row + params)
• Component (element props)
• Events (setVal detail)

Examples

Required PDF upload

<hb-input-file
  schemaentry="{&quot;id&quot;:&quot;contract&quot;,&quot;label&quot;:&quot;Contract (PDF)&quot;,&quot;required&quot;:true,&quot;validationTip&quot;:&quot;Please upload a PDF.&quot;,&quot;params&quot;:{&quot;accept&quot;:&quot;application/pdf,.pdf&quot;}}"
  show_validation="yes"
  i18nlang="en"
></hb-input-file>

Image placeholder (accept + preview dimensions)

<hb-input-file
  schemaentry="{&quot;id&quot;:&quot;avatar&quot;,&quot;label&quot;:&quot;Profile photo&quot;,&quot;required&quot;:true,&quot;validationTip&quot;:&quot;Select an image.&quot;,&quot;params&quot;:{&quot;accept&quot;:&quot;image/*&quot;,&quot;placeHolderImage&quot;:{&quot;src&quot;:&quot;https://example.com/placeholder.png&quot;,&quot;width&quot;:300,&quot;height&quot;:300}}}"
  i18nlang="en"
></hb-input-file>

Optional attachment (not required)

<hb-input-file
  schemaentry="{&quot;id&quot;:&quot;attachment&quot;,&quot;label&quot;:&quot;Attachment (optional)&quot;,&quot;required&quot;:false}"
></hb-input-file>

Italian UI

<hb-input-file
  schemaentry="{&quot;id&quot;:&quot;allegato&quot;,&quot;label&quot;:&quot;Allegato&quot;,&quot;required&quot;:true,&quot;validationTip&quot;:&quot;Seleziona un file.&quot;}"
  i18nlang="it"
></hb-input-file>

Listen for setVal

<script>
  const el = document.querySelector("hb-input-file");
  el.addEventListener("setVal", (e) => {
    console.log(e.detail.id, e.detail.valid, e.detail.value);
  });
</script>

Behavior notes

• Clear resets the native input value, revokes any object URL used for preview, and dispatches setVal with updated value / valid.
• MIME / extension — If the browser does not report a MIME type, the component guesses from the file extension against a built-in map for icon selection.
• hb-form — When embedded in hb-form, align i18nlang and show_validation with the form host for consistent UX.