|
| 1 | +--- |
| 2 | +componentId: tooltip |
| 3 | +title: Tooltip |
| 4 | +status: Alpha |
| 5 | +source: https://github.com/primer/react/tree/main/src/Tooltip |
| 6 | +storybook: '/react/storybook?path=/story/composite-components-tooltip' |
| 7 | +description: Use tooltips to add context to elements on the page. |
| 8 | +--- |
| 9 | + |
| 10 | +Tooltip only appears on mouse hover or keyboard focus and contain a label or description text. Use tooltips sparingly and as a last resort. [Consider these alternatives](https://primer.style/design/accessibility/tooltip-alternatives). |
| 11 | + |
| 12 | +import {Tooltip, IconButton, Button} from '@primer/react' |
| 13 | +import {BellIcon, MentionIcon} from '@primer/octicons-react' |
| 14 | +import InlineCode from '@primer/gatsby-theme-doctocat/src/components/inline-code' |
| 15 | + |
| 16 | +<Box |
| 17 | + sx={{ |
| 18 | + display: 'flex', |
| 19 | + justifyContent: 'center', |
| 20 | + border: '1px solid', |
| 21 | + borderColor: 'border.default', |
| 22 | + borderRadius: 2, |
| 23 | + padding: 6, |
| 24 | + paddingTop: 8, |
| 25 | + marginBottom: 3 |
| 26 | + }} |
| 27 | +> |
| 28 | + <Tooltip text="You have no unread notifications" sx={{visibility: 'visible', opacity: 1}}> |
| 29 | + <IconButton icon={BellIcon} aria-label="Notifications" /> |
| 30 | + </Tooltip> |
| 31 | +</Box> |
| 32 | + |
| 33 | +When using a tooltip, follow the provided guidelines to avoid accessibility issues: |
| 34 | + |
| 35 | +- Tooltip text should be brief and to the point. |
| 36 | +- Tooltips should contain only **non-essential text**. Tooltips can easily be missed and are not accessible on touch devices so never use tooltips to convey critical information. |
| 37 | + |
| 38 | +## Examples |
| 39 | + |
| 40 | +### As a description for icon-only button |
| 41 | + |
| 42 | +If the tooltip content provides supplementary description, wrap the target in a `Tooltip`. The trigger element should also have a concise accessible label via `aria-label`. |
| 43 | + |
| 44 | +```jsx live |
| 45 | +<Tooltip text="Directly mention a team or user"> |
| 46 | + <IconButton aria-label="Mentions" icon={MentionIcon} variant="invisible" /> |
| 47 | +</Tooltip> |
| 48 | +``` |
| 49 | + |
| 50 | +### As a description for a button with visible label |
| 51 | + |
| 52 | +```jsx live |
| 53 | +<Tooltip text="This will immediately impact all organization members"> |
| 54 | + <Button variant="primary">Save</Button> |
| 55 | +</Tooltip> |
| 56 | +``` |
| 57 | + |
| 58 | +### With direction |
| 59 | + |
| 60 | +Set direction of tooltip with `direction`. The tooltip is responsive and will automatically adjust direction to avoid cutting off. |
| 61 | + |
| 62 | +```jsx live |
| 63 | +<Box |
| 64 | + sx={{ |
| 65 | + display: 'flex', |
| 66 | + flexDirection: 'column', |
| 67 | + gap: 8, |
| 68 | + marginY: 4, |
| 69 | + '[data-component=tooltip]': {visibility: 'visible', opacity: 1} |
| 70 | + }} |
| 71 | +> |
| 72 | + <Box sx={{display: 'flex', justifyContent: 'space-between', gap: 1}}> |
| 73 | + <Tooltip direction="nw" text="Tooltip text"> |
| 74 | + <Button>North west</Button> |
| 75 | + </Tooltip> |
| 76 | + <Tooltip direction="n" text="Tooltip text"> |
| 77 | + <Button>North</Button> |
| 78 | + </Tooltip> |
| 79 | + <Tooltip direction="ne" text="Tooltip text"> |
| 80 | + <Button>North east</Button> |
| 81 | + </Tooltip> |
| 82 | + </Box> |
| 83 | + <Box sx={{display: 'flex', justifyContent: 'space-between', gap: 1}}> |
| 84 | + <Tooltip direction="e" text="Tooltip text"> |
| 85 | + <Button>East</Button> |
| 86 | + </Tooltip> |
| 87 | + <Tooltip direction="w" text="Tooltip text"> |
| 88 | + <Button>West</Button> |
| 89 | + </Tooltip> |
| 90 | + </Box> |
| 91 | + <Box sx={{display: 'flex', justifyContent: 'space-between', gap: 1}}> |
| 92 | + <Tooltip direction="sw" text="Tooltip text"> |
| 93 | + <Button>South west</Button> |
| 94 | + </Tooltip> |
| 95 | + <Tooltip direction="s" text="Tooltip text"> |
| 96 | + <Button>South</Button> |
| 97 | + </Tooltip> |
| 98 | + <Tooltip direction="se" text="Tooltip text"> |
| 99 | + <Button>South east</Button> |
| 100 | + </Tooltip> |
| 101 | + </Box> |
| 102 | +</Box> |
| 103 | +``` |
| 104 | + |
| 105 | +## Props |
| 106 | + |
| 107 | +### Tooltip |
| 108 | + |
| 109 | +<PropsTable> |
| 110 | + <PropsTableRow name="children" required type="React.ReactNode" description="Tooltip target, single element" /> |
| 111 | + |
| 112 | + <PropsTableRow |
| 113 | + name="text" |
| 114 | + type="string" |
| 115 | + description="The text content of the tooltip. This should be brief and no longer than a sentence" |
| 116 | + /> |
| 117 | + <PropsTableRow |
| 118 | + deprecated |
| 119 | + name="aria-label" |
| 120 | + type="string" |
| 121 | + description={ |
| 122 | + <> |
| 123 | + Use <InlineCode>text</InlineCode> instead |
| 124 | + </> |
| 125 | + } |
| 126 | + /> |
| 127 | + <PropsTableRow |
| 128 | + name="type" |
| 129 | + type="'description' | 'label'" |
| 130 | + defaultValue="'description'" |
| 131 | + description={ |
| 132 | + <> |
| 133 | + Use <InlineCode>aria-describedby</InlineCode> or <InlineCode>aria-labelledby</InlineCode> |
| 134 | + </> |
| 135 | + } |
| 136 | + /> |
| 137 | + <PropsTableRow |
| 138 | + name="direction" |
| 139 | + type="'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w'" |
| 140 | + defaultValue="'n'" |
| 141 | + description="Sets where the tooltip renders in relation to the target" |
| 142 | + /> |
| 143 | + <PropsTableRow name="align" deprecated type="'left' | 'right'" description="Use direction instead. Alignment relative to target" /> |
| 144 | + <PropsTableRow |
| 145 | + name="noDelay" |
| 146 | + type="boolean" |
| 147 | + defaultValue="false" |
| 148 | + description={ |
| 149 | + <> |
| 150 | + When set to <InlineCode>true</InlineCode>, tooltip appears without any delay |
| 151 | + </> |
| 152 | + } |
| 153 | + /> |
| 154 | + <PropsTableRow |
| 155 | + name="wrap" |
| 156 | + type="boolean" |
| 157 | + deprecated |
| 158 | + description={ |
| 159 | + <> |
| 160 | + Use to allow text within tooltip to wrap. Deprecated: always set to <InlineCode>true</InlineCode> now. |
| 161 | + </> |
| 162 | + } |
| 163 | + /> |
| 164 | + <PropsTableSxRow /> |
| 165 | +</PropsTable> |
| 166 | + |
| 167 | +## Status |
| 168 | + |
| 169 | +<ComponentChecklist |
| 170 | + items={{ |
| 171 | + propsDocumented: true, |
| 172 | + noUnnecessaryDeps: true, |
| 173 | + adaptsToThemes: true, |
| 174 | + adaptsToScreenSizes: true, |
| 175 | + fullTestCoverage: true, |
| 176 | + usedInProduction: true, |
| 177 | + usageExamplesDocumented: true, |
| 178 | + hasStorybookStories: true, |
| 179 | + designReviewed: false, |
| 180 | + a11yReviewed: false, |
| 181 | + stableApi: true, |
| 182 | + addressedApiFeedback: false, |
| 183 | + hasDesignGuidelines: false, |
| 184 | + hasFigmaComponent: true |
| 185 | + }} |
| 186 | +/> |
| 187 | + |
| 188 | +## Further reading |
| 189 | + |
| 190 | +- [Tooltip alternatives](https://primer.style/design/accessibility/tooltip-alternatives) |
| 191 | + |
| 192 | +## Related components |
| 193 | + |
| 194 | +- [IconButton](/IconButton) |
0 commit comments