Getting Started

Get started with the File Explorer. Install the package, configure your application and start using the components.

Installation

Using your favorite package manager, install @stoked-ui/file-explorer:

npm install @stoked-ui/file-explorer

The File Explorer package has a peer dependency on @mui/material. If you are not already using it in your project, you can install it with:

npm install @stoked-ui/file-explorer @mui/material @emotion/react @emotion/styled

Please note that react and react-dom are peer dependencies too:

"peerDependencies": {
  "react": "^17.0.0 || ^18.0.0",
  "react-dom": "^17.0.0 || ^18.0.0"
},

Style engine

Material UI is using Emotion as a styling engine by default. If you want to use styled-components instead, run:

npm install @stoked-ui/file-explorer @mui/material @mui/styled-engine-sc styled-components

Take a look at the Styled engine guide for more information about how to configure styled-components as the style engine.

Render your first component

To make sure that everything is set up correctly, try rendering a FileExplorerBasic component:

Notes
Images
Movies
Data

<FileExplorerBasic getItemId>
    <FileElement name={"Notes"}>
      <FileElement name="doc.pdf" />
      <FileElement name="notes.txt" />
    </FileElement>
    <FileElement name={"Images"}>
      <FileElement name={"logo.png"} />
      <FileElement name={"favicon.ico"} />
    </FileElement>
    <FileElement name={"Movies"}>
      <FileElement name={"feature.mp4"} />
    </FileElement>
    <FileElement name={"Data"}>
      <FileElement name={"client-data.xls"} />
    </FileElement>
</FileExplorerBasic>

<FileExplorerBasic getItemId>
    <FileElement name={"Notes"}>
      <FileElement name="doc.pdf" />
      <FileElement name="notes.txt" />
    </FileElement>
    <FileElement name={"Images"}>
      <FileElement name={"logo.png"} />
      <FileElement name={"favicon.ico"} />
    </FileElement>
    <FileElement name={"Movies"}>
      <FileElement name={"feature.mp4"} />
    </FileElement>
    <FileElement name={"Data"}>
      <FileElement name={"client-data.xls"} />
    </FileElement>
</FileExplorerBasic>

Press Enter to start editing

Accessibility

(WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/)

The component follows the WAI-ARIA authoring practices.

To have an accessible file explorer you must use aria-labelledby or aria-label to reference or provide a label on the FileExplorer, otherwise, screen readers will announce it as "tree", making it hard to understand the context of a specific tree item.

TypeScript

In order to benefit from the CSS overrides and default prop customization with the theme, TypeScript users need to import the following types. Internally, it uses module augmentation to extend the default theme structure.

// When using TypeScript 4.x and above
import type {} from '@stoked-ui/file-explorer/themeAugmentation';
// When using TypeScript 3.x and below
import '@stoked-ui/file-explorer/themeAugmentation';

const theme = createTheme({
  components: {
    MuiFileExplorer: {
      styleOverrides: {
        root: {
          backgroundColor: 'red',
        },
      },
    },
  },
});

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.