tubestation/toolkit/content/widgets/moz-input-folder

MozInputFolder

moz-input-folder is a reusable component that provides the ability to browse and pick a folder from the file system. It displays the path and icon of the selected folder to the user. It can also be configured to display custom text if needed.

<div style={{width: "500px"}} onClickCapture={e => e.stopPropagation()}>
  <moz-input-folder
    label="Save files to"
    placeholder="Select folder">
  </moz-input-folder>
</div>

Usage guidelines

When to use

• Use moz-input-folder when you want to allow a user to select a directory.

When not to use

• When users need to select individual files rather than folders.

Code

The source for moz-input-folder can be found under toolkit/content/widgets/moz-input-folder/

How to use moz-input-folder

Importing the element

Like other custom elements, you should usually be able to rely on moz-input-folder getting lazy loaded at the time of first use. See this documentation for more information on using design system custom elements.

Setting the label

Providing a label for the moz-input-folder component is crucial for usability and accessibility:

• Helps users understand the purpose of the folder picker.
• Improves accessibility by ensuring screen readers can announce the function of the input.

To set a label, use the label attribute. In general, the label should be controlled by Fluent.

<moz-input-folder label="Label text"></moz-input-folder>

<div style={{width: '500px'}} onClickCapture={e => e.stopPropagation()}>
  <moz-input-folder label="Label text"></moz-input-folder>
</div>

Setting the description

In order to set a description, use the description attribute. In general, the description should be controlled by Fluent. This is the the preferred way of setting descriptions since it ensures consistency across instances of moz-input-folder.

<moz-input-folder label="Label" description="Description text"></moz-input-folder>

<div style={{width: '500px'}} onClickCapture={e => e.stopPropagation()}>
  <moz-input-folder
    label="Label"
    description="Description text">
  </moz-input-folder>
</div>

However, moz-input-folder does support a slot element if your use case is more complex.

<moz-input-folder label="Label">
  <span slot="description">A more complex description</span>
</moz-input-folder>

<div style={{width: "500px"}} onClickCapture={e => e.stopPropagation()}>
  <moz-input-folder label="Label">
    <span slot="description">A more <b>complex</b> description</span>
  </moz-input-folder>
</div>

Setting the value

The value attribute of moz-input-folder sets the initial folder path displayed in the input field. When a new folder is selected, the value gets updated with that folder's path.

<moz-input-folder label="Save files to:" value="/User/Downloads"></moz-input-folder>

<div style={{width: '500px'}} onClickCapture={e => e.stopPropagation()}>
  <moz-input-folder label="Save files to:" value="/User/Downloads"></moz-input-folder>
</div>

Setting the displayValue

Use displayValue property to display something other than a folder path in the input element. Listen to the moz-input-folder change event to set a displayValue after the new folder was selected. The folder property represents the selected folder in the file system (nsIFile object). You can use properties of the folder when setting a displayValue (e.g., folder.path, folder.displayName or folder.leafName).

<moz-input-folder label="Save files to:" value="/User/Downloads" displayvalue="Downloads"></moz-input-folder>

// Code example
let mozInputFolder = document.querySelector("moz-input-folder");
mozInputFolder.addEventListener(
  "change",
  () => {
    mozInputFolder.displayValue = mozInputFolder.folder.displayName;
  }
);

<div style={{width: '500px'}} onClickCapture={e => e.stopPropagation()}>
  <moz-input-folder label="Save files to:" value="/User/Downloads" displayvalue="Downloads"></moz-input-folder>
</div>

Setting the disabled state

In order to disable the moz-input-folder, add disabled="" or disabled to the markup with no value.

<moz-input-folder label="Label" disabled></moz-input-folder>

<div style={{width: '500px'}} onClickCapture={e => e.stopPropagation()}>
  <moz-input-folder label="Label" disabled></moz-input-folder>
</div>

Setting the accesskey

accesskey defines an keyboard shortcut for the input.

<moz-input-folder label="Label with accesskey" accesskey="L"></moz-input-folder>

<div style={{width: '500px'}} onClickCapture={e => e.stopPropagation()}>
  <moz-input-folder label="Label with accesskey" accesskey="L"></moz-input-folder>
</div>

Fluent usage

The label, description, placeholder and accesskey attributes of moz-input-folder will generally be provided via Fluent attributes. The relevant data-l10n-attrs are set automatically, so to get things working you just need to supply a data-l10n-id as you would with any other element.

For example, the following Fluent messages:

moz-input-folder-label =
  .label = Save files to
moz-input-folder-placeholder =
  .label = Save files to
  .placeholder = Select folder
moz-input-folder-description =
  .label = Save files to
  .description = Description text
  .placeholder = Select folder
moz-input-folder-with-accesskey =
  .label = Save files to
  .accesskey = v

would be used to set text and attributes on the different moz-input-folder elements as follows:

<moz-input-folder data-l10n-id="moz-input-folder-label"></moz-input-folder>
<moz-input-folder data-l10n-id="moz-input-folder-placeholder"></moz-input-folder>
<moz-input-folder data-l10n-id="moz-input-folder-description"></moz-input-folder>
<moz-input-folder data-l10n-id="moz-input-folder-with-accesskey"></moz-input-folder>