Components / Controls

PathField

A file or folder path: a text field with a Browse button inside its end that asks your app's picker for a path, and a clear button. The path can also be typed. It is for apps with their own file dialog (Electron), where a browser file input gives no path.

Source Edit this page

Browse fills the path

When to use

A setting or form value that is a path on disk: a database file, an export folder, a binary.
Your app has a native dialog that returns a path (Electron's dialog.showOpenDialog over IPC).

Use something else when:

people upload files from a web page: FileDrop
the value is ordinary text: TextField

Usage

tsx

import { PathField } from "@arshad-shah/cynosure";

<PathField
  label="Database file"
  name="db"
  value={path}
  onChange={setPath}
  onPick={() => window.api.pickFile({ filters: [{ name: "SQLite", extensions: ["db"] }] })}
/>

onPick returns a promise of the chosen path, or null when the dialog was cancelled. While it is open the Browse button is busy and cannot be pressed again; a cancel, or a picker that fails (the promise rejects), leaves the path as it was. FileDrop's onPick works the same way.

Cancelling changes nothing

Controlled use and forms

value and onChange control the path; onChange is called when it is typed, picked or cleared. With name, the path is submitted with its form, and required blocks the form while it is empty. The Browse button never submits.

Controlled value

Sizes, icon and labels

size (xs, sm, md, lg) sets the field, and the Browse button is one step smaller so it fits inside. iconStart leads the field with an icon (a folder). labels replaces the button text ("Browse…", "Clear").

Props

Every prop of PathField
Prop	What it does	Type	Default
`label`Required	The field's label and accessible name.	`ReactNode`
`onPick`Required	Opens your picker (Electron's `dialog.showOpenDialog` over IPC, a file system access handle) and resolves with the chosen path, or null when it was cancelled. The button is busy until it settles; a cancel or a failure (the promise rejects) leaves the path as it was.	`() => Promise<string \| null>`
`labelHidden`	Visually hide the label (it still names the field). Prefer visible labels.	`boolean`
`description`	Help text shown below the field and read with it.	`ReactNode`
`error`	Your own error message, shown below the field.	`ReactNode`
`value`	The path (controlled).	`string`
`defaultValue`	The path at first, when uncontrolled.	`string`
`onChange`	Called with the new path when it is typed, picked or cleared.	`((value: string) => void)`
`name`	Name the path is submitted under in a form.	`string`
`form`	Id of the form it belongs to, when it is not inside that form.	`string`
`required`	The form cannot be submitted while the path is empty.	`boolean`
`disabled`	Turns off the field and its buttons; the path is not submitted.	`boolean`
`placeholder`	Hint shown in the field while it is empty.	`string`
`iconStart`	Icon at the start of the field.	`IconData`
`size`	Field height and text size. Default "md".	`DenseSize`	`"md"`
`variant`	`outline` or `soft` (tinted, borderless until focus). Default "outline".	`"soft" \| "outline"`	`"outline"`
`labels`	Replace the built-in English text: the Browse and clear buttons.	`Partial<PathFieldLabels>`
`className`	Added to the root element, for layout.	`string`
`style`	Layout only. Restyle through --cy-path-field-* tokens.	`CSSProperties`
`layout`	`stack` puts the label above the control and the description and error below it. `split` puts the label and description at the start and the control at the end of one row (a settings row); when the field is too narrow for both, the control moves under the text. Default "stack".	`"stack" \| "split"`	`"stack"`
`width`	Width of the control, so the controls of a column of fields line up: "sm", "md" and "lg" are the `--cy-field-control-width-*` tokens (never wider than the field), "full" is the whole field. Default: the control's own width (the whole field in the stacked layout for TextField and the other fields).	`FieldWidth`

Generated from the type definitions in @arshad-shah/cynosure 0.5.0.

Behaviour and accessibility

Behaviour and accessibility, table 1
Input	Result
Typing	Edits the path
`TabTab`	The input, then the clear button (while there is a path), then Browse
`EnterEnter` or a press on Browse	Calls `onPick`; the chosen path fills the field
A press on the clear button	Empties the field and focuses it

Roles: a labelled text box, a "Clear" button and a "Browse…" button, aria-busy while the picker is open.
Disabled: the field and Browse are disabled and the clear button is gone; the path is not submitted.
Right to left: the buttons end the field, on the left.

Touch

The Browse button has a 44px hit area on touch screens (the clear button is TextField's, sized the same way).

Theming

Tokens: --cy-path-field-browse-inset (space between the Browse button and the field's end), and TextField's and Button's for the field and the button.

TextField · FileDrop · Button

These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.

When to useLink to "When to use"

UsageLink to "Usage"

Controlled use and formsLink to "Controlled use and forms"

Sizes, icon and labelsLink to "Sizes, icon and labels"

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

TouchLink to "Touch"

ThemingLink to "Theming"

RelatedLink to "Related"