# @doc-blocks/gallery
> The `Gallery` component lets you easily showcase an example from each on of your components.
Latest version **0.8.15** (published 2022-07-25) · MIT license · 0 weekly downloads
## Install
```sh
npm install @doc-blocks/gallery
pnpm add @doc-blocks/gallery
yarn add @doc-blocks/gallery
bun add @doc-blocks/gallery
```
## Health
**Score 30/100 (F)** — status: abandoned.
Positive: has types; esm support; no vulnerabilities; high quality score.
Warnings: low downloads; pre 1.0.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 0.8.15 |
| Published | 2022-07-25 |
| First published | 2020-10-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 7 |
| Unpacked size | 98.1 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | Andrew Lisowski lisowski54@gmail.com |
| Maintainers | alisowski |
## Links
- npm: https://www.npmjs.com/package/@doc-blocks/gallery
- Repository: https://github.com/intuit/doc-blocks
- Homepage: https://github.com/intuit/doc-blocks#readme
- Issues: https://github.com/intuit/doc-blocks/issues
- npm.io page: https://npm.io/package/@doc-blocks/gallery
## Dependencies (7)
- [fast-glob](https://npm.io/package/fast-glob.md) ^3.1.1
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) 7.11.2
- [@doc-blocks/row](https://npm.io/package/@doc-blocks/row.md) ^0.8.15
- [@doc-blocks/shield](https://npm.io/package/@doc-blocks/shield.md) ^0.8.15
- [@doc-blocks/shield-row](https://npm.io/package/@doc-blocks/shield-row.md) ^0.8.15
- [@doc-blocks/design-spec](https://npm.io/package/@doc-blocks/design-spec.md) ^0.8.15
- [use-isomorphic-layout-effect](https://npm.io/package/use-isomorphic-layout-effect.md) 1.0.0
## Recent versions
- 0.8.15 (latest) — 2022-07-25
- 1.0.0--canary.34.14719242015.0 (canary) — 2025-04-28
- 0.8.16--canary.2.14718503897.0 — 2025-04-28
- 0.8.16--canary.2.14718455217.0 — 2025-04-28
- 0.8.16--canary.2.14718423516.0 — 2025-04-28
- 0.8.16--canary.2.14323049859.0 — 2025-04-28
- 0.8.15-canary.26.580.0 — 2022-07-25
- 0.8.14 — 2022-07-25
- 0.8.14-canary.25.569.0 — 2022-07-25
- 0.8.13 — 2022-03-09
- 0.8.13-canary.24.553.0 — 2022-03-09
- 0.8.12 — 2021-11-15
- 0.8.12-canary.22.542.0 — 2021-11-15
- 0.8.11 — 2021-10-22
- 0.8.11-canary.21.533.0 — 2021-10-22
- … 51 more at https://npm.io/package/@doc-blocks/gallery/versions
## README
# @doc-blocks/gallery
The `Gallery` component lets you easily showcase an example from each on of your components.
[Demo](https://intuit.github.io/doc-blocks/?path=/story/gallery--page)
## Installation
```sh
npm i @doc-blocks/gallery
# or with yarn
yarn add @doc-blocks/gallery
```
## Usage
### Create the Gallery page
Then create an MDX only story that renders the `Gallery` component.
```md
import { Meta } from '@storybook/addon-docs/blocks';
import { Gallery } from '@doc-blocks/gallery';
# Gallery
A showcase of frequently-used components.
```
## Props
All of the props are optional.
### Component props
- `excludedComponents` - Component names to exclude from the gallery
- `matchPath` - Storybook folder path or regex that looks for stories to generate components (ex: `Features`)
- `titleStory` - Story to make the component title link to
### Story name props
Props that determine which stories appear under each component, allowing users to quickly navigate pages without opening folders in the sidebar.
- `includedStoryNames` - Story names to include from the gallery (default: [`Basic`])
- `excludedStoryNames` - Story names to exclude from the gallery
### Add to webpack
If you want the components to have a description and link to the design spec add the following to your storybook's webpack configuration.
You must provide a function that will gather information about your components that the `Gallery` component uses to create the gallery.
This function should return an array of component specs that have the following data:
- `name` (required)
- `description`
- `type`
- `url`
```js
const { createGallerySpecs } = require("@doc-blocks/gallery/specs");
function getSpecs() {
// Return and array of component specs
return [{ name: "Button", description: "A button to go clicky clicky" }];
}
module.exports = async (config) => {
config.plugins.push(await createGallerySpecs({ specs: getSpecs() }));
return config;
};
```
## Intuit's `getOverviewSpecs`
This package also includes `getOverviewSpecs` which depends on the way we structure our stories.
This works wonderfully with [`@design-systems/cli`](https://github.com/intuit/design-systems-cli/) and [`@doc-blocks/design-spec`].
If the component follows the structure we define it is automatically included in the `Gallery` without any other configuration.
**Structure:**
1. All of your components are located in a directory named `components/`
2. Each component has a MDX only entry point named `Overview.stories.mdx`
For each `Overview.stories.mdx` that is found `createGallerySpecs` will gather the following information:
- `name` - The name of the component defined in `Meta.title`
- `description` - The first sentence from the component's `README.md`
- `type` - The type of design spec defined in the `DesignSpec` component
- `url` - The url of design spec defined in the `DesignSpec` component
**Example `Overview.stories.mdx`**
```md
import { Meta, Description, Title } from '@storybook/addon-docs/blocks';
import { Version, RelatedComponents, ShieldRow, DesignSpec, BundleSize } from 'storybook-doc-blocks';
import notes from '../../README.md';
import { version } from '../../package.json';
import BadgeDocs from './Badge.mdx';
@cgds/badge
---
```
Just modify the webpack configuration to use this function:
```js
const {
createGallerySpecs,
getOverviewSpecs,
} = require("@doc-blocks/gallery/specs");
module.exports = async (config) => {
config.plugins.push(
createGallerySpecs({
specs: await getOverviewSpecs({
componentDirectory: path.join(__dirname, "../components"),
}),
})
);
return config;
};
```
---
_Source: https://npm.io/package/@doc-blocks/gallery · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._