{"id":13571474,"url":"https://github.com/4lejandrito/react-guitar","last_synced_at":"2025-04-09T08:03:17.453Z","repository":{"id":40269212,"uuid":"281020585","full_name":"4lejandrito/react-guitar","owner":"4lejandrito","description":"A beautiful and accessible guitar component for React. ⚛️ 🎸 ","archived":false,"fork":false,"pushed_at":"2023-03-06T17:31:41.000Z","size":23974,"stargazers_count":630,"open_issues_count":7,"forks_count":47,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-11-24T16:50:50.944Z","etag":null,"topics":["guitar","react"],"latest_commit_sha":null,"homepage":"https://react-guitar.com","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/4lejandrito.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"4lejandrito","custom":["https://buymeacoffee.com/b4iusc3"]}},"created_at":"2020-07-20T05:18:24.000Z","updated_at":"2024-11-17T17:10:28.000Z","dependencies_parsed_at":"2024-01-14T03:51:25.203Z","dependency_job_id":"ad75168f-d34e-4f06-b938-a24e458e630e","html_url":"https://github.com/4lejandrito/react-guitar","commit_stats":{"total_commits":315,"total_committers":2,"mean_commits":157.5,"dds":0.006349206349206327,"last_synced_commit":"45e813acd8dd250ab9dda1509199d9f1d929feb4"},"previous_names":[],"tags_count":64,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4lejandrito%2Freact-guitar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4lejandrito%2Freact-guitar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4lejandrito%2Freact-guitar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4lejandrito%2Freact-guitar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/4lejandrito","download_url":"https://codeload.github.com/4lejandrito/react-guitar/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247999859,"owners_count":21031046,"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":["guitar","react"],"created_at":"2024-08-01T14:01:02.324Z","updated_at":"2025-04-09T08:03:17.430Z","avatar_url":"https://github.com/4lejandrito.png","language":"TypeScript","funding_links":["https://github.com/sponsors/4lejandrito","https://buymeacoffee.com/b4iusc3"],"categories":["TypeScript"],"sub_categories":[],"readme":"# React-Guitar \u0026middot; [![npm version](https://img.shields.io/npm/v/react-guitar.svg?style=flat)](https://www.npmjs.com/package/react-guitar)\n\nA beautiful and accessible guitar component for React.\n\nSee https://react-guitar.com for a live demo.\n\n![Screenshot of the rendered component with an E major chord](packages/react-guitar/screenshot.png)\n\n[![Edit quizzical-dawn-0hzuq](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/interesting-breeze-ll7zh)\n\n### Projects using React-Guitar\n\n- [Workland](https://github.com/cgm42/WorkLand) ([GIF](https://github.com/cgm42/WorkLand#guitar---thanks-to-react-guitar)) - A metaverse for tech teams.\n\n## Usage\n\n```\nnpm i react-guitar\n```\n\n```jsx\nimport React from 'react'\nimport { render } from 'react-dom'\nimport Guitar from 'react-guitar'\n\nrender(\n  \u003cGuitar strings={[0, 1, 2, 2, 0, -1]} /\u003e,\n  document.getElementById('root')\n)\n```\n\nCheck out [the storybook](https://react-guitar.com/storybook) for more advanced examples.\n\n### Props\n\n| Name           | Description                                                                                                                                                                                                                               |\n| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `id`           | An optional id in case several guitars are on the screen at the same time. This is used to generate the radio button names used internally which must be unique. If not specified an autoincremented id will be generated.                |\n| `className`    | A CSS class string to apply to the container element.                                                                                                                                                                                     |\n| `strings`      | An array where each number represents the fret the string is pressed on (`0` means open string and `-1` muted). `[0, 1, 2, 2, 0, -1]` is an `A minor` in a standard guitar and `[3, 0, 0, 0]` is a `C major` in a ukelele.                |\n| `frets`        | An object with the shape `{ from: number amount: number }` to configure the frets of the guitar (`{ from: 0, amount: 22 }` by default). It can start on any fret which is useful for displaying just a chord instead of the whole guitar. |\n| `lefty`        | A boolean to configure the guitar for left handed people like me.                                                                                                                                                                         |\n| `center`       | A boolean to indicate if the current fretting should be centered. If set to `true` the guitar horizontal scroll will be set so that the middle fret is centered.                                                                          |\n| `renderFinger` | A function `(string: number, fret: number) =\u003e JSX.Element` that will be used to render the content of the white bubble used for the fingers. This can be used to render the note name.                                                    |\n| `theme`        | A theme object to customise the guitar look and feel. See [Theming](#theming).                                                                                                                                                            |\n| `playOnHover`  | A boolean to indicate if hovering with the mouse should trigger play events.                                                                                                                                                              |\n| `onChange`     | A function `(strings: number[]) =\u003e void` that will be called when a string is press/unpressed. If not present the guitar will be read only.                                                                                               |\n| `onPlay`       | A function `(string: number) =\u003e void` that will be called each time the user plays a string (hovering with the mouse). This can be used to play the sound of the string.                                                                  |\n\n### Hooks\n\n#### useSound\n\nIn order to enable sound playing `react-guitar` offers the [useSound](packages/react-guitar-sound) hook:\n\n```\nnpm i react-guitar react-guitar-sound react-guitar-tunings\n```\n\n```jsx\nimport React, { useMemo } from 'react'\nimport { render } from 'react-dom'\nimport Guitar from 'react-guitar'\nimport { standard } from 'react-guitar-tunings'\nimport useSound from 'react-guitar-sound'\n\nfunction SampleGuitarWithSound() {\n  const strings = useMemo(() =\u003e [0, 1, 2, 2, 0, -1], [])\n  const { play, strum } = useSound({ fretting: strings, tuning: standard })\n\n  return \u003cGuitar strings={strings} onPlay={play} /\u003e\n}\n\nrender(\u003cSampleGuitarWithSound /\u003e, document.getElementById('root'))\n```\n\n[![Edit quizzical-dawn-0hzuq](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/trusting-monad-hfbbh?file=/src/index.js)\n\nIt receives an object with the following properties:\n| Name | Description |\n| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `fretting` | The same value passed as the `strings` prop to the `\u003cGuitar /\u003e` component with the current fretting. |\n| `tuning` | An array of midi values for each string. See [react-guitar-tunings](packages/react-guitar-tunings) for a list of the most common ones.|\n| `instrument` | Optionally the instrument to use, an acousting nylon guitar by default.\n\nAnd will return an object containing:\n\n| Name    | Description                                                           |\n| ------- | --------------------------------------------------------------------- |\n| `play`  | A function that receives a string number and plays its current sound. |\n| `strum` | A function that will strum all the strings of the guitar.             |\n\nThere are 2 ways to create a custom instrument:\n\n1. Using `withSoundFont`:\n\n   ```jsx\n   import React, { useMemo } from 'react'\n   import { render } from 'react-dom'\n   import Guitar from 'react-guitar'\n   import { standard } from 'react-guitar-tunings'\n   import useSound, { withSoundFont } from 'react-guitar-sound'\n\n   const electricGuitar = withSoundFont('electric_guitar_clean')\n\n   function SampleGuitarWithSound() {\n     const strings = useMemo(() =\u003e [0, 1, 2, 2, 0, -1], [])\n     const { play, strum } = useSound({\n       instrument: electricGuitar,\n       fretting: strings,\n       tuning: standard,\n     })\n\n     return \u003cGuitar strings={strings} onPlay={play} /\u003e\n   }\n\n   render(\u003cSampleGuitarWithSound /\u003e, document.getElementById('root'))\n   ```\n\n   It uses [danigb/soundfont-player](https://github.com/danigb/soundfont-player) under the hood so [all these instrument names](https://github.com/danigb/soundfont-player/blob/master/names/musyngkite.json) are available.\n\n2. Using `withSamples`:\n\n   ```jsx\n   import React, { useMemo } from 'react'\n   import { render } from 'react-dom'\n   import Guitar from 'react-guitar'\n   import { standard } from 'react-guitar-tunings'\n   import useSound, { withSamples } from 'react-guitar-sound'\n\n   const flamencoGuitar = withSamples({\n     E2: 'https://react-guitar.com/samples/E2.mp3',\n     D3: 'https://react-guitar.com/samples/D3.mp3',\n     G3: 'https://react-guitar.com/samples/G3.mp3',\n     E4: 'https://react-guitar.com/samples/E4.mp3',\n   })\n\n   function SampleGuitarWithSound() {\n     const strings = useMemo(() =\u003e [0, 1, 2, 2, 0, -1], [])\n     const { play, strum } = useSound({\n       instrument: flamencoGuitar,\n       fretting: strings,\n       tuning: standard,\n     })\n\n     return \u003cGuitar strings={strings} onPlay={play} /\u003e\n   }\n\n   render(\u003cSampleGuitarWithSound /\u003e, document.getElementById('root'))\n   ```\n\n### Theming\n\n`react-guitar` look and feel can be customised by passing the `theme` prop. A theme is an object describing the customisable properties of the guitar:\n\n```tsx\n{\n  description: string // for screen readers\n  color: string\n  nut: { color: string }\n  fret: {\n    color: string\n    separator: {\n      color: string\n      radius?: boolean\n      shadow?: boolean\n      width?: 'sm' | 'md'\n    }\n    marker?: (fret: number) =\u003e JSX.Element | null\n    counter: { color: string }\n  }\n  string: { color: (string: number) =\u003e string }\n  finger: { text: { color: string }; color: string }\n}\n```\n\nSee https://react-guitar.com/storybook/?path=/story/guitar--theming for an interactive example.\n\nBy default the guitar is styled as a Spanish guitar but some other themes are available:\n\n- [react-guitar-theme-dark](packages/react-guitar-theme-dark): A dark theme.\n- [react-guitar-theme-coco](packages/react-guitar-theme-coco): A theme for the guitar from the [Coco](\u003chttps://en.wikipedia.org/wiki/Coco_(2017_film)\u003e) film.\n\n## Upgrading from 0.x\n\nIf you were using `useSound` like this:\n\n```jsx\nuseSound(\n  {\n    E2: '...E2.mp3',\n    D3: '...D3.mp3',\n    G3: '...G3.mp3',\n    E4: '...E4.mp3',\n  },\n  strings,\n  tuning\n)\n```\n\nYou need to change it to:\n\n```jsx\nimport useSound, { withSamples } from 'react-guitar-sound'\n\n// outside the render function\nconst instrument = withSamples({\n  E2: 'https://react-guitar.com/samples/E2.mp3',\n  D3: 'https://react-guitar.com/samples/D3.mp3',\n  G3: 'https://react-guitar.com/samples/G3.mp3',\n  E4: 'https://react-guitar.com/samples/E4.mp3',\n})\n\n// inside the render function\nuseSound({\n  instrument,\n  fretting: strings,\n  tuning,\n})\n```\n\n## Developing\n\n- `yarn build` will build the component and the site, this is mandatory the first time you clone the repo.\n- `yarn start` will spin up the storybook and the site and all the packages in watch mode.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4lejandrito%2Freact-guitar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F4lejandrito%2Freact-guitar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4lejandrito%2Freact-guitar/lists"}