Skip to main content
Neighborhood Design System v5.1.0

Upload

Draft

A file upload field with drag and drop, file type and size limits, and a list of selected files.

Draft. This component is in draft. Its API may change before it is marked Ready. What this means

Preview

Open in Storybook (opens in new tab)

Code

Install
npm install @fbin-web/neighborhood-core
Import
import { NbhdUpload } from '@fbin-web/neighborhood-core';
Usage
<nbhd-upload
  label="Upload photos"
  help-text="Add a clear photo of the product label."
  upload-type="image"
  multiple
  max-files="3"
  max-file-size="5242880">
</nbhd-upload>

<script>
  const nbhdUpload = document.querySelector('nbhd-upload');

  nbhdUpload.addEventListener('nbhd-files-selected', (event) => {
    console.log(event.detail.files);
  });
</script>

Properties

PropertyAttributeTypeDefaultDescription
labellabelstring''Visible label for the upload field.
helpTexthelp-textstring''Help text shown below the drop zone when not invalid.
errorTexterror-textstring''Error text shown when invalid is set.
invalidinvalidbooleanfalseMarks the upload as invalid and shows the error text.
instructionsinstructionsstring'Drag and drop a file here or'Text inside the drop zone, before the browse button. Uses "files" when multiple is set.
browseLabelbrowse-labelstring'Browse files'Label for the browse button.
browseVariantbrowse-variantprimarysecondarytertiaryplainlinkunstyled'primary'Button variant for the browse button.
uploadTypeupload-typeimagefile'image'Preset of accepted file types. Ignored when accept is set.
acceptacceptstring''Native accept string that overrides upload-type, e.g. image/*,.pdf.
multiplemultiplebooleanfalseAllows more than one file. Without it, a new file replaces the current one.
maxFilesmax-filesnumber—Maximum number of files when multiple is set.
maxFileSizemax-file-sizenumber—Maximum size of each file, in bytes.
namenamestring''Field name for consumers to use when appending files to FormData. The form field name it submits under.
disableddisabledbooleanfalseDisables the browse button, drop zone and remove buttons.
requiredrequiredbooleanfalseAt least one file must be chosen before the owning form submits. Shows the required marker on the label.
requiredLabelrequired-labelstringRequiredAnnounced with the Browse button when `required`, since the visual * marker is hidden from screen readers.
surfacesurfacenoneprimarysecondaryinverseinverse-secondary'primary'Surface the upload sits on. Colors follow the surface control colors.
ariaLabelaria-labelstring''Accessible name used when no visible label is set.
fileListLabelfile-list-labelstringSelected filesAccessible name of the list of selected files.
cssClasscss-classstring''Custom CSS class for the base wrapper.
files—File[][]Read-only copy of the selected files.

Events

NameDescriptionEvent Detail
nbhd-files-selectedEmitted when files are added or removed.{ files: File[] }
nbhd-files-rejectedEmitted when files are not added because of their type, size or the file limit.{ rejected: { file: File, reason: 'type' | 'size' | 'count' }[] }
nbhd-file-removedEmitted when a file is removed from the selection.{ file: File, files: File[] }

Form methods

Form-associated: submits the chosen files under `name` (one entry per file). With `required`, no file blocks submission. Reset clears the selection.

NameDescription
checkValidity()Returns false (and fires `invalid`) if the control fails validation.
reportValidity()Like checkValidity(), and shows the browser’s validation message on the control.
setCustomValidity(message)Marks the control invalid with your own message; an empty string clears it.
validityThe ValidityState (valueMissing, typeMismatch, customError, …).
validationMessageThe message the browser would show.
willValidateWhether the control takes part in form validation (false when disabled).
associatedFormThe
the control belongs to, or null.

Slots

NameDescription
labelCustom content for the label. Defaults to the label property.
iconReplaces the upload icon in the drop zone.
instructionsReplaces the drop zone instructions text.
helpHelp text shown when not invalid.
errorError text shown when invalid.
requirementsReplaces the generated accepted types and limits text.

CSS Parts

NameDescription
baseThe form control wrapper.
labelThe label wrapper.
dropzoneThe drag and drop area.
iconThe icon wrapper.
instructionsThe instructions wrapper.
browse-buttonThe browse button.
textThe wrapper for help, error, rejection and requirements text.
helpThe help slot.
errorThe error slot.
rejectionsThe list of files that were not added.
requirementsThe requirements slot.
file-listThe list of selected files.
fileA selected file.
thumbnailThe image preview or file type icon.
file-nameThe file name.
file-metaThe file size.
remove-buttonThe remove button for a file.
nbhd-upload::part(base) {
  /* your styles */
}

CSS Properties

Set these on nbhd-upload or an ancestor to override the defaults. Token is the design token a default comes from and Value is what it resolves to in core Neighborhood; brands may override them. Properties that adapt to surface follow the light or inverse surface they sit on until you set them.

Upload

PropertyTokenValue Copy
--nbhd-upload-dropzone-alignItems—center
--nbhd-upload-dropzone-backgroundColor—transparent
--nbhd-upload-dropzone-borderColor--nbhd-context-color-control-borderAdapts to surface
--nbhd-upload-dropzone-borderRadius--nbhd-border-radius-md6px
--nbhd-upload-dropzone-borderStyle—dashed
--nbhd-upload-dropzone-borderWidth--nbhd-border-width-emphasis2px
--nbhd-upload-dropzone-color--nbhd-context-color-control-foregroundAdapts to surface
--nbhd-upload-dropzone-cursor—pointer
--nbhd-upload-dropzone-disabled-cursor—not-allowed
--nbhd-upload-dropzone-dragover-backgroundColor-opacity—0.06
--nbhd-upload-dropzone-dragover-borderStyle—solid
--nbhd-upload-dropzone-gap--nbhd-space-312px
--nbhd-upload-dropzone-minBlockSize—140px
--nbhd-upload-dropzone-paddingBlock--nbhd-space-624px
--nbhd-upload-dropzone-paddingInline--nbhd-space-416px
--nbhd-upload-dropzone-textAlign—center
--nbhd-upload-dropzone-transitionDuration--nbhd-motion-duration-normal0.2s
--nbhd-upload-file-backgroundColor--nbhd-context-color-control-backgroundAdapts to surface
--nbhd-upload-file-borderColor--nbhd-context-color-control-borderAdapts to surface
--nbhd-upload-file-borderRadius--nbhd-border-radius-sm2px
--nbhd-upload-file-borderStyle—solid
--nbhd-upload-file-borderWidth--nbhd-border-width-subtle1px
--nbhd-upload-file-color--nbhd-context-color-control-foregroundAdapts to surface
--nbhd-upload-file-gap--nbhd-space-312px
--nbhd-upload-file-paddingBlock--nbhd-space-28px
--nbhd-upload-file-paddingInline--nbhd-space-312px
--nbhd-upload-fileList-gap--nbhd-space-28px
--nbhd-upload-gap--nbhd-space-28px
--nbhd-upload-host-display—block
--nbhd-upload-icon-color--nbhd-context-color-text-secondaryAdapts to surface
--nbhd-upload-icon-marginBlockEnd—0.25rem
--nbhd-upload-icon-size--nbhd-size-icon-xxl48px
--nbhd-upload-inlineSize—100%
--nbhd-upload-maxInlineSize—100%
--nbhd-upload-thumbnail-borderRadius--nbhd-border-radius-sm2px
--nbhd-upload-thumbnail-objectFit—cover
--nbhd-upload-thumbnail-size--nbhd-size-thumbnail56px

Form control

PropertyTokenValue Copy
--nbhd-formControl-display—inline
--nbhd-formControl-field-appearance—none
--nbhd-formControl-field-borderRadius--nbhd-border-radius-none0
--nbhd-formControl-field-color--nbhd-context-color-control-foregroundAdapts to surface
--nbhd-formControl-field-display—inline-block
--nbhd-formControl-field-fontFamily--nbhd-typography-body-fontFamilysans-serif
--nbhd-formControl-field-fontSize--nbhd-typography-body-fontSize1rem
--nbhd-formControl-field-inlineSize—100%
--nbhd-formControl-field-position—relative
--nbhd-formControl-fontFamily--nbhd-typography-body-fontFamilysans-serif
--nbhd-formControl-host-display—block
--nbhd-formControl-label-color--nbhd-context-color-text-primaryAdapts to surface
--nbhd-formControl-label-display—block
--nbhd-formControl-label-fontFamily--nbhd-typography-label-fontFamilysans-serif
--nbhd-formControl-label-fontSize--nbhd-typography-label-fontSize1rem
--nbhd-formControl-label-fontWeight--nbhd-typography-label-fontWeight600
--nbhd-formControl-label-letterSpacing—inherit
--nbhd-formControl-label-marginBlock--nbhd-space-0 --nbhd-space-050px 2px
--nbhd-formControl-label-position—relative
--nbhd-formControl-label-textTransform—inherit
--nbhd-formControl-marginBlock--nbhd-space-00px
--nbhd-formControl-maxInlineSize—100%
--nbhd-formControl-paddingBlock--nbhd-space-00px
--nbhd-formControl-paddingInline--nbhd-space-00px
--nbhd-formControl-position—relative
--nbhd-formControl-required-gap--nbhd-space-052px
--nbhd-formControl-text-marginBlock--nbhd-space-1 --nbhd-space-04px 0px

Dependencies

Child components <nbhd-upload> renders internally. Import them too when you tree-shake.

Esc
↑ ↓ to move↵ to open