{"id":18952791,"url":"https://github.com/nickofthyme/storybook-addon-toggles","last_synced_at":"2025-07-01T14:31:31.574Z","repository":{"id":169845137,"uuid":"642592633","full_name":"nickofthyme/storybook-addon-toggles","owner":"nickofthyme","description":"List of options toggles","archived":false,"fork":false,"pushed_at":"2023-05-27T01:31:38.000Z","size":710,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-17T14:04:37.960Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nickofthyme.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-18T23:33:36.000Z","updated_at":"2023-05-18T23:33:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"b04a29b8-70a4-437c-b774-e6002ec1a8f0","html_url":"https://github.com/nickofthyme/storybook-addon-toggles","commit_stats":null,"previous_names":["nickofthyme/storybook-addon-toggles"],"tags_count":1,"template":false,"template_full_name":"storybookjs/addon-kit","purl":"pkg:github/nickofthyme/storybook-addon-toggles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickofthyme%2Fstorybook-addon-toggles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickofthyme%2Fstorybook-addon-toggles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickofthyme%2Fstorybook-addon-toggles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickofthyme%2Fstorybook-addon-toggles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nickofthyme","download_url":"https://codeload.github.com/nickofthyme/storybook-addon-toggles/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickofthyme%2Fstorybook-addon-toggles/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260527609,"owners_count":23022797,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T13:34:38.371Z","updated_at":"2025-07-01T14:31:31.535Z","avatar_url":"https://github.com/nickofthyme.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Storybook Addon Toggle\n\nThis addon is used to add a list of user defined global toggles that are accessible and customizable at the story level. All options are explained below, see [Parameters](#parameters) section below.\n\nTest it out at https://nickofthyme.github.io/storybook-addon-toggles/\n\n![Screen Recording 2023-05-26 at 11 24 24 AM](https://github.com/nickofthyme/storybook-addon-toggles/assets/19007109/c709d87f-faa5-41e8-a434-709238a92f6f)\n\n## Compatibility\n\nThis version is compatible with storybook version `\u003e6.x`.\n\nAs of storybook `6.3.0` global parameters are synced with the url as query search params ([storybookjs/storybook#15056](https://github.com/storybookjs/storybook/pull/15056)). As such this will lock-in the default global and be persisted between stories. If you want to avoid this behavior you should use `storybook@~6.2.0`.\n\n## Installation\n\n### yarn\n```sh\nyarn add -D storybook-addon-toggles\n```\n\n### npm\n```sh\nnpm i -D storybook-addon-toggles\n```\n\n## Getting started\n\nOnce installed, add this addon to the `addons` array in storybooks `main.js` file:\n\n```jsx\n// main.js\nmodule.exports = {\n  addons: [\n    'storybook-addon-toggles'\n  ],\n};\n```\n\nSee the [storybook documentation](https://storybook.js.org/docs/addons/using-addons/) for more information.\n\n## Parameters\n\nThe parameters for this plugin are under the `toggles` key and are defined below.\n\n```tsx\nexport interface Parameters\u003cToggleId extends string = string\u003e {\n  /**\n   * Ignores global values in url params\n   *\n   * @default true\n   */\n  ignoreQueryParams?: false;\n  /**\n   * Toggle options\n   */\n  options: ToggleOptions\u003cToggleId\u003e[];\n  /**\n   * Toggle default overrides from story level\n   */\n  overrides: Record\u003cToggleId, boolean\u003e;\n  /**\n   * Enabled clearing all toggles to default values\n   *\n   * @default true\n   */\n  clearable?: boolean;\n  /**\n   * Addon is disabled at story level\n   *\n   * @default false\n   */\n  disabled?: boolean;\n  /**\n   * Override icon used in toolbar\n   * See https://github.com/storybookjs/storybook/blob/release/6.2/lib/components/src/icon/icons.tsx\n   *\n   * @default 'form'\n   */\n  icon?: IconsProps['icon'];\n  /**\n   * A callback that will be executed when the toggles change\n   */\n  onChange?: (Toggles?: Toggles) =\u003e void;\n}\n```\n\nThe `ToggleOptions` type is defined below.\n\n```tsx\nexport type ToggleKey = string;\nexport type ToggleValue = boolean\nexport type Toggles = Record\u003cstring, ToggleValue\u003e;\n\nexport interface ToggleOptions\u003cT extends string = string\u003e {\n  /**\n   * id of the toggle\n   */\n  id: T;\n  /**\n   * Title of the toggle in Selector UI\n   */\n  title?: string;\n  /**\n   * Description of the toggle, shows in title on hover\n   */\n  description?: string;\n  /**\n   * Default value\n   */\n  defaultValue: ToggleValue;\n  /**\n   * Disable toggle by boolean or list of dependent toggles\n   */\n  disabled?: boolean | Toggles;\n}\n```\n\n## Configuration\n\n### Global level\n\nYou can configure the toggles at the global level in the storybook `preview.(ts|js)` file as demonstrated below.\n\n```tsx\n// preview.ts\n\nimport type { TogglesParameter } from 'storybook-addon-toggles';\n\ntype Parameters = TogglesParameter \u0026 {\n  // other global types\n};\n\nexport const parameters: Parameters = {\n  toggles: {\n    ignoreQueryParams: false,\n    icon: 'form',\n    options: [\n      {\n        id: 'option-1',\n        title: 'Option 1',\n        description: 'Some description of option 1',\n        defaultValue: false,\n      },\n      {\n        id: 'option-2',\n        title: 'Option 2',\n        defaultValue: true,\n      },\n      {\n        id: 'option-3',\n        title: 'Option 3',\n        defaultValue: true,\n        disabled: {\n          \"option-2\": false\n        }\n      },\n    ],\n  }\n};\n\n```\n\n### Story level\n\nAll properties defined in `TogglesParameter` are capable of being overridden at the story level. However, it is only advisable to override some of the parameters to prevent defining parameters that could negatively affect the addon behavior across all stories. The acceptable properties include `overrides`, `options`, `disabled`, `ignoreQueryParams` and `clearable`. The `BackgroundStoryParameter` type is a helper that should be used to limit what properties are overridden at the story level.\n\n```tsx\n// story.stories.tsx\n\nimport type { StoryTogglesParameter } from 'storybook-addon-toggles';\n\nconst Example = () =\u003e \u003cspan\u003eHello!\u003c/span\u003e;\n\nExample.parameters = {\n  toggles: {\n    overrides: {\n      'option-1': false,\n    }\n  }\n} as StoryTogglesParameter;\n```\n\n## Usage of globals context\n\n### Storys\n\nEach story is rendered with two parameters, the first is the `args` from `Story.bind(myArgs)`, the second is the `StoryContext`. The `StoryContext` gives us direct access to the globals.\n\n```tsx\n// story.stories.tsx\n\nconst Example = (args, context) =\u003e {\n  return \u003cspan\u003eValue of Option 1: ${context.globals.toggles['option-1']}\u003c/span\u003e\n};\n```\n\n\n### Decorators\n\nGlobal storybook [`Decorators`](https://storybook.js.org/docs/react/writing-stories/decorators#global-decorators) can be used for a multitude of things. As such it is important to have access to the toggles inside the decorators. This is the primary reason for chosing to use `globals` to maintain the state of the toggles.\n\nBelow is a simple example of how you could access the toggles via the `context.globals`.\n\n```tsx\n// preview.tsx\n\nimport React from \"react\";\n\nimport type { DecoratorFunction } from \"@storybook/addons\";\nimport type { TogglesGlobals } from 'storybook-addon-toggles';\n\nconst Decorator: DecoratorFunction\u003cJSX.Element\u003e = (Story, context) =\u003e {\n  const globals = context.globals as TogglesGlobals;\n  const toggles = globals.toggles; // object of all toggle values\n\n  return (\n    \u003cdiv\u003e\n      \u003cStory {...context} /\u003e\n      \u003cbr /\u003e\n      \u003cpre\u003e\n        // Toggle values\n        {JSON.stringify(toggles, null, 2)}\n      \u003c/pre\u003e\n    \u003c/div\u003e\n  );\n};\n\nexport const decorators = [Decorator];\n```\n\nSee a full example of this in [`.storybook/Decorator.tsx`](.storybook/Decorator.tsx).\n\n\u003e Globals are currently not correctly initialized by storybook, meaning they *always* return `{}` as the initial value. To correct this, we update globals with the default/initial toggles once the `SET_STORIES` event is emitted, if they differ.\n\n## Framework Support\n\n| [React](https://reactjs.org/) |\n|:-:|\n| :white_check_mark: |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickofthyme%2Fstorybook-addon-toggles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnickofthyme%2Fstorybook-addon-toggles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickofthyme%2Fstorybook-addon-toggles/lists"}