@salesforce-ux/design-system/__internal/chunked/docs/ui/components/buttons/docs.mdx.js

Salesforce Lightning Design System

var SLDS="object"==typeof SLDS?SLDS:{};SLDS["__internal/chunked/docs/./ui/components/buttons/docs.mdx.js"]=function(e){function t(t){for(var s,o,c=t[0],r=t[1],i=t[2],d=0,b=[];d<c.length;d++)o=c[d],Object.prototype.hasOwnProperty.call(a,o)&&a[o]&&b.push(a[o][0]),a[o]=0;for(s in r)Object.prototype.hasOwnProperty.call(r,s)&&(e[s]=r[s]);for(u&&u(t);b.length;)b.shift()();return l.push.apply(l,i||[]),n()}function n(){for(var e,t=0;t<l.length;t++){for(var n=l[t],s=!0,c=1;c<n.length;c++){var r=n[c];0!==a[r]&&(s=!1)}s&&(l.splice(t--,1),e=o(o.s=n[0]))}return e}var s={},a={13:0},l=[];function o(t){if(s[t])return s[t].exports;var n=s[t]={i:t,l:!1,exports:{}};return e[t].call(n.exports,n,n.exports,o),n.l=!0,n.exports}o.m=e,o.c=s,o.d=function(e,t,n){o.o(e,t)||Object.defineProperty(e,t,{enumerable:!0,get:n})},o.r=function(e){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},o.t=function(e,t){if(1&t&&(e=o(e)),8&t)return e;if(4&t&&"object"==typeof e&&e&&e.__esModule)return e;var n=Object.create(null);if(o.r(n),Object.defineProperty(n,"default",{enumerable:!0,value:e}),2&t&&"string"!=typeof e)for(var s in e)o.d(n,s,function(t){return e[t]}.bind(null,s));return n},o.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return o.d(t,"a",t),t},o.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},o.p="/assets/scripts/bundle/";var c=this.webpackJsonpSLDS___internal_chunked_docs=this.webpackJsonpSLDS___internal_chunked_docs||[],r=c.push.bind(c);c.push=t,c=c.slice();for(var i=0;i<c.length;i++)t(c[i]);var u=r;return l.push([751,0]),n()}({0:function(e,t){e.exports=React},20:function(e,t){e.exports=ReactDOM},22:function(e,t){e.exports=JSBeautify},751:function(e,t,n){"use strict";n.r(t),n.d(t,"getElement",(function(){return L})),n.d(t,"getContents",(function(){return P}));var s=n(0),a=n.n(s),l=n(4),o=n(2),c=(n(27),n(14)),r=n(40),i=n(12),u=n(9),d=[{id:"default",label:"Default",element:a.a.createElement(i.a,{isNeutral:!0},a.a.createElement(u.a,{className:"slds-button__icon slds-button__icon_left",sprite:"utility",symbol:"download"}),"Button Neutral")}],b=(i.a,u.a,[{id:"with-icon-right",label:"With right icon",element:a.a.createElement(i.a,{isNeutral:!0},"Button Neutral",a.a.createElement(u.a,{className:"slds-button__icon slds-button__icon_right",sprite:"utility",symbol:"download"}))}]),h=n(127),f=n(3),m=n.n(f),p=n(5),g=n.n(p);function y(e,t){return function(e){if(Array.isArray(e))return e}(e)||function(e,t){var n=null==e?null:"undefined"!=typeof Symbol&&e[Symbol.iterator]||e["@@iterator"];if(null==n)return;var s,a,l=[],o=!0,c=!1;try{for(n=n.call(e);!(o=(s=n.next()).done)&&(l.push(s.value),!t||l.length!==t);o=!0);}catch(e){c=!0,a=e}finally{try{o||null==n.return||n.return()}finally{if(c)throw a}}return l}(e,t)||function(e,t){if(!e)return;if("string"==typeof e)return O(e,t);var n=Object.prototype.toString.call(e).slice(8,-1);"Object"===n&&e.constructor&&(n=e.constructor.name);if("Map"===n||"Set"===n)return Array.from(e);if("Arguments"===n||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n))return O(e,t)}(e,t)||function(){throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}()}function O(e,t){(null==t||t>e.length)&&(t=e.length);for(var n=0,s=new Array(t);n<t;n++)s[n]=e[n];return s}var v=function(e){return a.a.createElement("span",{className:"slds-text-not-pressed"},a.a.createElement(u.a,{className:"slds-button__icon slds-button__icon_small slds-button__icon_left",sprite:"utility",symbol:"add"}),e.children)};v.propTypes={children:m.a.string.isRequired};var j=function(e){return a.a.createElement("span",{className:"slds-text-pressed"},a.a.createElement(u.a,{className:"slds-button__icon slds-button__icon_small slds-button__icon_left",sprite:"utility",symbol:"check"}),e.children)};j.propTypes={children:m.a.string.isRequired};var w=function(e){var t=e.isDisabled,n=e.isPressed,l=y(Object(s.useState)(n),2),o=l[0],c=l[1];return a.a.createElement(i.a,{isNeutral:!0,className:g()("slds-button_dual-stateful",{"slds-is-pressed":o}),disabled:t,"aria-live":"assertive","aria-pressed":Boolean(o).toString(),onClick:function(){return c(!o)}},a.a.createElement(v,null,"Follow"),a.a.createElement(j,null,"Following"))};w.propTypes={isDisabled:m.a.bool,isPressed:m.a.bool};var E=[{id:"default",label:"Default",element:a.a.createElement(w,null,a.a.createElement(v,null,"Follow"),a.a.createElement(j,null,"Following"))}],_=[{id:"pressed",label:"pressed",element:a.a.createElement(w,{isPressed:!0},a.a.createElement(v,null,"Follow"),a.a.createElement(j,null,"Following"))}],k=n(1),S=n(39),T=l.c.a,x=l.c.code,B=l.c.em,D=l.c.h2,A=l.c.h3,N=l.c.li,I=l.c.p,C=l.c.strong,F=l.c.ul,L=function(){return Object(s.createElement)(l.b,{},Object(s.createElement)("div",{className:"doc lead"},"Buttons are clickable items used to perform an action."),Object(s.createElement)(o.a,null,Object(s.createElement)(a.a.Fragment,null,Object(k.f)(i.b),Object(k.f)(i.c,"neutral"),Object(k.f)(i.c,"brand"),Object(k.f)(i.c,"outline-brand"),Object(k.f)(i.c,"destructive"),Object(k.f)(i.c,"text-destructive"),Object(k.f)(i.c,"success"))),D({id:"About-Buttons"},"About Buttons"),I({},"Buttons should be used in situations where users might need to:"),F({},N({},"submit a form"),N({},"begin a new task"),N({},"trigger a new UI element to appear on the page"),N({},"specify a new or next step in a process")),A({id:"Button-vs.-Link"},"Button vs. Link"),I({},"The HTML elements for buttons and links describe a very specific type of action that is going to be taken when they are used. It is important you know when to use which, as the distinction matters:"),F({},N({},"Use a ",C({},"link")," when you’re ",C({},"navigating to another place"),', such as: a "view all" page, "Jane Chen" profile, a page "skip link" etc.'),N({},"Use ",C({},"buttons")," when you are ",C({},"performing an action"),', such as: "submit," "merge," "create new," "upload," etc.'),N({},"An action is almost ",C({},"always")," on the same page")),A({id:"Accessibility"},"Accessibility"),I({},'If pressing a Button results in a new URL, or the resultant UI makes sense as "a new browser tab", that is a link ',x({},"<a>"),". Everything else is a ",x({},"<button>"),"."),I({},"The distinction is important to screen reader users to know what's going to happen next. Will I navigate somewhere or will something happen on the page? So it's important to choose the right HTML element for the job."),I({},"If you absolutely cannot use a ",x({},"<button />")," element for an action and instead need to use an ",x({},"<a />"),", you are required to do 2 things:"),F({},N({},"Add ",x({},'role="button"')," attribute to the ",x({},"<a />")," to make the element announce itself as a ",x({},"button")," element."),N({},"Add a JavaScript event handler for when the user presses the space key. This is because a ",x({},"button")," element will respond by default to both the enter and space keys being pressed, but an ",x({},"<a />")," element will not.")),I({},"Finally, color alone does not suffice when conveying the meaning of buttons. Ensure that the text you use in the button matches the meaning you are trying to convey via color. For example, if you use the destructive button to point out a potential warning, make sure the text communicates the same message."),Object(s.createElement)(o.a,null,Object(s.createElement)(a.a.Fragment,null,Object(k.f)(i.c,"base-link"),Object(k.f)(i.c,"neutral-link"),Object(k.f)(i.c,"brand-link"),Object(k.f)(i.c,"outline-brand-link"),Object(k.f)(i.c,"destructive-link"),Object(k.f)(i.c,"text-destructive-link"),Object(k.f)(i.c,"success-link"))),A({id:"Links-that-look-like-Buttons"},"Links that look like Buttons"),I({},'Use these with caution - dictation software users may not be able to properly identify these actions, as they can say "show buttons" and these won\'t highlight since they are semantically links, even though they may look like buttons.'),A({id:"Mobile"},"Mobile"),Object(s.createElement)(S.a,{patternSpecificText:"buttons will have an increased size to accommodate tapping with a finger instead of the more precise mouse cursor"}),Object(s.createElement)(o.a,{frameOnly:!0,frameTitle:"Example mobile styles for buttons"},Object(s.createElement)(a.a.Fragment,null,Object(k.f)(i.c,"base-link"),Object(k.f)(i.c,"neutral-link"),Object(k.f)(i.c,"brand-link"),Object(k.f)(i.c,"outline-brand-link"),Object(k.f)(i.c,"destructive-link"),Object(k.f)(i.c,"text-destructive-link"),Object(k.f)(i.c,"success-link"))),D({id:"Base"},"Base"),I({},"The base ",x({},"slds-button")," looks like a plain text link. It removes all the styling of the native button."),I({},"The base and neutral buttons are used most frequently and can be used multiple times per feature. Use these buttons when the actions are of secondary importance to the content surrounding it, such as in the actions ribbon in a page header."),Object(s.createElement)(o.a,{toggleCode:!1},Object(k.f)(i.b)),D({id:"Variations"},"Variations"),A({id:"Neutral"},"Neutral"),I({},"Add the ",x({},"slds-button_neutral")," class to create a neutral button."),Object(s.createElement)(o.a,{toggleCode:!1},Object(k.f)(i.c,"neutral")),A({id:"Brand"},"Brand"),I({},"To create the brand button, add the ",x({},"slds-button_brand")," class to the ",x({},"slds-button")," class. The brand color tokens can be overridden for theme specific usage."),I({},"The Brand button generally should only be used once per component screen at any one time. It is used for when there is an action that is clearly more important than the other actions and you need to draw attention to it. An example is when you have a “Save” and “Cancel” button. The “Save” is the primary action."),I({},"Not all features need to have primary actions, sometimes the actions are secondary to the content and are all of equal importance."),Object(s.createElement)(o.a,{toggleCode:!1},Object(k.f)(i.c,"brand")),A({id:"Outline-Brand"},"Outline Brand"),I({},"To create the outline brand button, add the ",x({},"slds-button_outline-brand")," class to the ",x({},"slds-button")," class. The brand color tokens can be overridden for theme specific usage."),Object(s.createElement)(o.a,{toggleCode:!1},Object(k.f)(i.c,"outline-brand")),A({id:"Inverse"},"Inverse"),I({},"Use the inverse button on dark backgrounds. Add the ",x({},"slds-button_inverse")," class to the ",x({},"slds-button")," class."),Object(s.createElement)(o.a,{toggleCode:!1},Object(k.f)(i.c,"inverse")),A({id:"Destructive"},"Destructive"),I({},"To create the destructive button, add the ",x({},"slds-button_destructive")," class to the ",x({},"slds-button")," class."),I({},"This button is used to indicate a destructive action to the user, like permanently erasing data."),Object(s.createElement)(o.a,{toggleCode:!1},Object(k.f)(i.c,"destructive")),A({id:"Text-Destructive"},"Text Destructive"),I({},"To create the text destructive button, add the ",x({},"slds-button_text-destructive")," class to the ",x({},"slds-button")," class."),I({},"This button is used to indicate a destructive action to the user, like permanently erasing data. Use this version when the ",T({href:"#Destructive"},"Destructive")," button would be too distracting to the experience."),Object(s.createElement)(o.a,{toggleCode:!1},Object(k.f)(i.c,"text-destructive")),A({id:"Success"},"Success"),I({},"To create the success button, add the ",x({},"slds-button_success")," class to the ",x({},"slds-button")," class."),Object(s.createElement)(o.a,{toggleCode:!1},Object(k.f)(i.c,"success")),D({id:"Disabled"},"Disabled"),I({},"Use a disabled attribute when a button can’t be clicked. To create a disabled button, append the ",x({},"disabled")," attribute to the button."),Object(s.createElement)(o.a,null,Object(s.createElement)(a.a.Fragment,null,Object(k.f)(i.d,"disabled"),Object(k.f)(i.d,"neutral-disabled"),Object(k.f)(i.d,"brand-disabled"),Object(k.f)(i.d,"outline-brand-disabled"),Object(k.f)(i.d,"destructive-disabled"),Object(k.f)(i.d,"text-destructive-disabled"),Object(k.f)(i.d,"success-disabled"))),D({id:"With-Icons"},"With Icons"),I({},"The SVG, element, or icon inside the button receives the ",x({},"slds-button__icon")," class. You can position the icon on the left or the right using ",x({},"slds-button__icon_left")," or ",x({},"slds-button__icon_right"),", which applies the correct amount of space between the icon and the text."),A({id:"Left-Icon"},"Left Icon"),Object(s.createElement)(o.a,null,Object(k.f)(d)),Object(s.createElement)(S.b,{docsLink:"#Mobile",header:"Mobile context changes",elementName:"button icons"}),Object(s.createElement)(o.a,{frameOnly:!0,frameTitle:"Example mobile styles for buttons with left icon"},Object(k.f)(d)),A({id:"Right-Icon"},"Right Icon"),Object(s.createElement)(o.a,null,Object(k.f)(b,"with-icon-right")),D({id:"Stateful"},"Stateful"),I({},"Stateful buttons have three states: not selected (default), selected and focused, and selected with hover state."),I({},"The stateful button requires the ",x({},"slds-button_stateful")," class and the ",x({},"slds-button_neutral")," class in addition to the ",x({},"slds-button")," class. Stateful buttons are only used with the neutral variation."),I({},"The button contains three spans with classes that hide or show the content of the spans based on the class on the button. Each span contains text and a corresponding icon. The SVG will have the ",x({},"slds-button__icon_left")," class setting the icon on the left."),Object(s.createElement)(c.a,{type:"a11y",header:"Accessibility Requirement"},Object(s.createElement)("p",null,"The stateful button should have ",Object(s.createElement)("code",null,'aria-pressed="true"')," or ",Object(s.createElement)("code",null,'"false"'),' and the accessible label should be static and describe the pressed state, so for example a "follow" button would always say "follow" and the sense that you are "following" is actually derived from ',Object(s.createElement)("code",null,"aria-pressed")," being true. Also, be sure to include the attribute ",Object(s.createElement)("code",null,'aria-live="assertive"')," on the button. The ",Object(s.createElement)("code",null,'aria-live="assertive"')," attribute means the value of the ",Object(s.createElement)("code",null,"<span>")," inside the button will be spoken whenever it changes.")),Object(s.createElement)(c.a,{type:"note",header:"JavaScript Requirement"},Object(s.createElement)("p",null,"When the user clicks the button, use JavaScript to toggle the class from"," ",Object(s.createElement)("code",null,"slds-not-selected")," to ",Object(s.createElement)("code",null,"slds-is-selected-clicked"),". As soon as focus leaves the button, use JavaScript to toggle the class from"," ",Object(s.createElement)("code",null,"slds-is-selected-clicked")," to ",Object(s.createElement)("code",null,"slds-is-selected"),".")),A({id:"Not-Selected"},"Not Selected"),I({},"Stateful button uses the class ",x({},"slds-not-selected")," in its initial state."),Object(s.createElement)(o.a,null,Object(k.f)(h.b)),A({id:"Selected-and-Focused"},"Selected and Focused"),I({},"When selected and still focused, stateful button uses the class ",x({},"slds-is-selected-clicked"),"."),Object(s.createElement)(o.a,null,Object(k.f)(h.c,"selected-clicked")),A({id:"Selected-with-Hover-State"},"Selected with Hover State"),I({},"Once selected and blurred (user moved focus away from the button), stateful button uses the class ",x({},"slds-is-selected"),"."),Object(s.createElement)(o.a,null,Object(k.f)(h.c,"selected")),D({id:"Dual-Stateful-Button"},"Dual Stateful Button"),I({},"Dual Stateful buttons have two states, similar to a ",T({href:"/accessibility/patterns/togglebutton/#site-main-content"},"Toggle Button"),": not pressed (default), and pressed."),I({},"The Dual Stateful button requires the ",x({},"slds-button_dual-stateful")," class, along with a combination of the ",x({},"slds-button")," and ",x({},"slds-button_neutral")," classes. While Dual Stateful buttons are only used with the neutral Button variation, the pressed state changes the button ",B({},"style")," to that of the Brand variation."),I({},"The button contains two spans. Each span contains display text and a corresponding SVG icon with the class ",x({},"slds-button__icon-left")," and has classes that hide or show the contents. By default, the first span with the class ",x({},"slds-text-is-not-pressed")," is displayed; when the class ",x({},"slds-is-pressed")," is applied to the parent button, the span with the class ",x({},"slds-text-is-pressed")," is displayed."),Object(s.createElement)(c.a,{type:"a11y",header:"Accessibility Requirement"},Object(s.createElement)("p",null,"The stateful button should have ",Object(s.createElement)("code",null,'aria-pressed="true"')," or ",Object(s.createElement)("code",null,'"false"'),' and the accessible label should be static and describe the pressed state, so for example a "follow" button would always say "follow" and the sense that you are "following" is actually derived from ',Object(s.createElement)("code",null,"aria-pressed")," being true. Also, be sure to include the attribute ",Object(s.createElement)("code",null,'aria-live="assertive"')," on the button. The ",Object(s.createElement)("code",null,'aria-live="assertive"')," attribute means the value of the ",Object(s.createElement)("code",null,"<span>")," inside the button will be spoken whenever it changes.")),Object(s.createElement)(c.a,{type:"note",header:"JavaScript Requirement"},Object(s.createElement)("p",null,"When the user clicks the button, use JavaScript to toggle the"," ",Object(s.createElement)("code",null,"slds-is-pressed")," class on or off, depending on the previous state. Remember, only the pressed state requires this class.")),A({id:"Not-Pressed"},"Not Pressed"),Object(s.createElement)(o.a,null,Object(k.f)(E)),A({id:"Pressed"},"Pressed"),I({},"To display the pressed state, use the class ",x({},"slds-is-pressed")," on the ",x({},"<button>")," element."),Object(s.createElement)(o.a,null,Object(k.f)(_,"pressed")),D({id:"Sizing"},"Sizing"),A({id:"Stretch"},"Stretch"),I({},"To allow the button's width to take up the entire width available, apply the ",x({},"slds-button_stretch")," class to the button."),Object(s.createElement)(o.a,{toggleCode:!1},Object(k.f)(i.c,"stretch")),A({id:"Full-Width"},"Full Width"),I({},"Creates a full width button with styling resets"),Object(s.createElement)(o.a,{toggleCode:!1},Object(k.f)(i.c,"full-width")),D({id:"Styling-Hooks-Overview"},"Styling Hooks Overview"),Object(s.createElement)(r.a,{name:"buttons",type:"component"}))},P=function(){return Object(l.a)(L())}}});