• Stars
    star
    618
  • Rank 70,753 (Top 2 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created almost 4 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A beautiful and accessible guitar component for React. โš›๏ธ ๐ŸŽธ

React-Guitar ยท npm version

A beautiful and accessible guitar component for React.

See https://react-guitar.com for a live demo.

Screenshot of the rendered component with an E major chord

Edit quizzical-dawn-0hzuq

Projects using React-Guitar

Usage

npm i react-guitar
import React from 'react'
import { render } from 'react-dom'
import Guitar from 'react-guitar'

render(
  <Guitar strings={[0, 1, 2, 2, 0, -1]} />,
  document.getElementById('root')
)

Check out the storybook for more advanced examples.

Props

Name Description
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.
className A CSS class string to apply to the container element.
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.
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.
lefty A boolean to configure the guitar for left handed people like me.
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.
renderFinger A function (string: number, fret: number) => 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.
theme A theme object to customise the guitar look and feel. See Theming.
playOnHover A boolean to indicate if hovering with the mouse should trigger play events.
onChange A function (strings: number[]) => void that will be called when a string is press/unpressed. If not present the guitar will be read only.
onPlay A function (string: number) => 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.

Hooks

useSound

In order to enable sound playing react-guitar offers the useSound hook:

npm i react-guitar react-guitar-sound react-guitar-tunings
import React, { useMemo } from 'react'
import { render } from 'react-dom'
import Guitar from 'react-guitar'
import { standard } from 'react-guitar-tunings'
import useSound from 'react-guitar-sound'

function SampleGuitarWithSound() {
  const strings = useMemo(() => [0, 1, 2, 2, 0, -1], [])
  const { play, strum } = useSound({ fretting: strings, tuning: standard })

  return <Guitar strings={strings} onPlay={play} />
}

render(<SampleGuitarWithSound />, document.getElementById('root'))

Edit quizzical-dawn-0hzuq

It receives an object with the following properties:

Name Description
fretting The same value passed as the strings prop to the <Guitar /> component with the current fretting.
tuning An array of midi values for each string. See react-guitar-tunings for a list of the most common ones.
instrument Optionally the instrument to use, an acousting nylon guitar by default.

And will return an object containing:

Name Description
play A function that receives a string number and plays its current sound.
strum A function that will strum all the strings of the guitar.

There are 2 ways to create a custom instrument:

  1. Using withSoundFont:

    import React, { useMemo } from 'react'
    import { render } from 'react-dom'
    import Guitar from 'react-guitar'
    import { standard } from 'react-guitar-tunings'
    import useSound, { withSoundFont } from 'react-guitar-sound'
    
    const electricGuitar = withSoundFont('electric_guitar_clean')
    
    function SampleGuitarWithSound() {
      const strings = useMemo(() => [0, 1, 2, 2, 0, -1], [])
      const { play, strum } = useSound({
        instrument: electricGuitar,
        fretting: strings,
        tuning: standard,
      })
    
      return <Guitar strings={strings} onPlay={play} />
    }
    
    render(<SampleGuitarWithSound />, document.getElementById('root'))

    It uses danigb/soundfont-player under the hood so all these instrument names are available.

  2. Using withSamples:

    import React, { useMemo } from 'react'
    import { render } from 'react-dom'
    import Guitar from 'react-guitar'
    import { standard } from 'react-guitar-tunings'
    import useSound, { withSamples } from 'react-guitar-sound'
    
    const flamencoGuitar = withSamples({
      E2: 'https://react-guitar.com/samples/E2.mp3',
      D3: 'https://react-guitar.com/samples/D3.mp3',
      G3: 'https://react-guitar.com/samples/G3.mp3',
      E4: 'https://react-guitar.com/samples/E4.mp3',
    })
    
    function SampleGuitarWithSound() {
      const strings = useMemo(() => [0, 1, 2, 2, 0, -1], [])
      const { play, strum } = useSound({
        instrument: flamencoGuitar,
        fretting: strings,
        tuning: standard,
      })
    
      return <Guitar strings={strings} onPlay={play} />
    }
    
    render(<SampleGuitarWithSound />, document.getElementById('root'))

Theming

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:

{
  description: string // for screen readers
  color: string
  nut: { color: string }
  fret: {
    color: string
    separator: {
      color: string
      radius?: boolean
      shadow?: boolean
      width?: 'sm' | 'md'
    }
    marker?: (fret: number) => JSX.Element | null
    counter: { color: string }
  }
  string: { color: (string: number) => string }
  finger: { text: { color: string }; color: string }
}

See https://react-guitar.com/storybook/?path=/story/guitar--theming for an interactive example.

By default the guitar is styled as a Spanish guitar but some other themes are available:

Upgrading from 0.x

If you were using useSound like this:

useSound(
  {
    E2: '...E2.mp3',
    D3: '...D3.mp3',
    G3: '...G3.mp3',
    E4: '...E4.mp3',
  },
  strings,
  tuning
)

You need to change it to:

import useSound, { withSamples } from 'react-guitar-sound'

// outside the render function
const instrument = withSamples({
  E2: 'https://react-guitar.com/samples/E2.mp3',
  D3: 'https://react-guitar.com/samples/D3.mp3',
  G3: 'https://react-guitar.com/samples/G3.mp3',
  E4: 'https://react-guitar.com/samples/E4.mp3',
})

// inside the render function
useSound({
  instrument,
  fretting: strings,
  tuning,
})

Developing

  • yarn build will build the component and the site, this is mandatory the first time you clone the repo.
  • yarn start will spin up the storybook and the site and all the packages in watch mode.

More Repositories

1

next-plausible

Simple integration for https://nextjs.org and https://plausible.io analytics
TypeScript
506
star
2

creepyface

The JavaScript library that makes your face look at the pointer. ๐Ÿคช๐Ÿ–ฑ๏ธ๐Ÿ‘†
TypeScript
486
star
3

fetchbook

Run and test your HTTP requests. Git friendly, 100% local.
TypeScript
147
star
4

rollup-plugin-browsersync

Serve your bundle via Browser Sync
JavaScript
19
star
5

liferay-pokemon-item-selector

Code for Liferay's /dev/24 talk
Java
12
star
6

storybook-tailwind2

Sample setup for Storybook and Tailwind@2
JavaScript
7
star
7

liferay-super-deploy

Deploy all changed modules at once (hopefully).
Shell
6
star
8

liferequest

From http://localhost:8080 to HTML
4
star
9

liferay-devcon-headless-2023

Liferay Devcon 2023 Headless Talk
FreeMarker
4
star
10

uptimerobot-node-client

NodeJS client for the uptimerobot API
JavaScript
3
star
11

elm-music-player

Music player written in Elm at a Haskell Madrid Meetup
Elm
2
star
12

emoji-chat

Emoji chat for WeDeploy Hackathon
JavaScript
2
star
13

npm-card

My NPM card ๐Ÿ’ณ
JavaScript
1
star
14

react-creepyface

React component for https://github.com/4lejandrito/creepyface.
1
star
15

me

My personal site
TypeScript
1
star
16

try_git

1
star
17

liferay-rest-client-for-templates

Example of a template migration from serviceLocator to restClient
FreeMarker
1
star
18

creepyface-firefly

A point provider for Creepyface
1
star
19

c2t-chrome

Car to Trello Chrome Extension
JavaScript
1
star
20

wercker-box-play

Wercker box for play 2.2.x apps
1
star
21

cliferay

Daily scripts to work with Liferay
Shell
1
star
22

liferay-headless-playwright

Playwright first steps for the Headless team
TypeScript
1
star