"use strict";(self.webpackChunkdocs=self.webpackChunkdocs||[]).push([[414],{6267:(e,t,n)=>{n.d(t,{Z:()=>o});var a=n(2983);const o=e=>{let{type:t,description:n,defaultValue:o}=e;return a.createElement("div",null,a.createElement("p",{style:{marginBottom:"0.25rem"}},n),a.createElement("ul",null,a.createElement("li",null,"Type: ",a.createElement("code",null,t)),o&&a.createElement("li",null,"Default: ",a.createElement("code",null,o))))}},830:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>s,contentTitle:()=>d,default:()=>m,frontMatter:()=>i,metadata:()=>p,toc:()=>u});var a=n(4321),o=(n(2983),n(4993)),l=n(6267),r=n(1475);const i={},d="PhoneInput API",p={unversionedId:"Usage/PhoneInput",id:"Usage/PhoneInput",title:"PhoneInput API",description:"PhoneInput is a highly customizable phone input component.",source:"@site/docs/02-Usage/01-PhoneInput.md",sourceDirName:"02-Usage",slug:"/Usage/PhoneInput",permalink:"/docs/Usage/PhoneInput",draft:!1,editUrl:"https://github.com/goveo/react-international-phone/tree/master/packages/docs/docs/02-Usage/01-PhoneInput.md",tags:[],version:"current",sidebarPosition:1,frontMatter:{},sidebar:"tutorialSidebar",previous:{title:"Getting Started",permalink:"/docs/getting-started"},next:{title:"Modify countries",permalink:"/docs/Usage/ModifyCountries"}},s={},u=[{value:"Usage Example",id:"usage-example",level:2},{value:"Properties",id:"properties",level:2},{value:"<code>value</code>",id:"value",level:3},{value:"<code>onChange</code>",id:"onchange",level:3},{value:"<code>defaultCountry</code>",id:"defaultcountry",level:3},{value:"<code>countries</code>",id:"countries",level:3},{value:"<code>preferredCountries</code>",id:"preferredcountries",level:3},{value:"<code>hideDropdown</code>",id:"hidedropdown",level:3},{value:"<code>disabled</code>",id:"disabled",level:3},{value:"<code>prefix</code>",id:"prefix",level:3},{value:"<code>defaultMask</code>",id:"defaultmask",level:3},{value:"<code>charAfterDialCode</code>",id:"charafterdialcode",level:3},{value:"<code>historySaveDebounceMS</code>",id:"historysavedebouncems",level:3},{value:"<code>disableCountryGuess</code>",id:"disablecountryguess",level:3},{value:"<code>disableDialCodePrefill</code>",id:"disabledialcodeprefill",level:3},{value:"<code>forceDialCode</code>",id:"forcedialcode",level:3},{value:"<code>disableDialCodeAndPrefix</code>",id:"disabledialcodeandprefix",level:3},{value:"<code>showDisabledDialCodeAndPrefix</code>",id:"showdisableddialcodeandprefix",level:3},{value:"<code>disableFocusAfterCountrySelect</code>",id:"disablefocusaftercountryselect",level:3},{value:"<code>disableFormatting</code>",id:"disableformatting",level:3},{value:"<code>flags</code>",id:"flags",level:3},{value:"<code>inputProps</code>",id:"inputprops",level:3},{value:"Style properties",id:"style-properties",level:2},{value:"CSS variables",id:"css-variables",level:2},{value:"Ref forwarding",id:"ref-forwarding",level:2},{value:"Ref additional properties",id:"ref-additional-properties",level:3},{value:"<code>setCountry</code>",id:"setcountry",level:4},{value:"<code>state</code>",id:"state",level:4},{value:"<code>ParsedCountry</code> type",id:"parsedcountry-type",level:2}],c={toc:u};function m(e){let{components:t,...n}=e;return(0,o.kt)("wrapper",(0,a.Z)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h1",{id:"phoneinput-api"},"PhoneInput API"),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"PhoneInput")," is a highly customizable phone input component."),(0,o.kt)("h2",{id:"usage-example"},"Usage Example"),(0,o.kt)("p",null,"Import component"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-tsx"},"import { PhoneInput } from 'react-international-phone';\n")),(0,o.kt)("p",null,"Use by providing the ",(0,o.kt)("em",{parentName:"p"},"defaultCountry"),", ",(0,o.kt)("em",{parentName:"p"},"value")," and ",(0,o.kt)("em",{parentName:"p"},"onChange")," callback."),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-tsx"},'<PhoneInput\n  defaultCountry="ua"\n  value={phone}\n  onChange={(phone) => setPhone(phone)}\n/>\n')),(0,o.kt)("p",null,"Output:"),(0,o.kt)(r.sb,{defaultCountry:"ua",mdxType:"PhoneInput"}),(0,o.kt)("h2",{id:"properties"},"Properties"),(0,o.kt)("h3",{id:"value"},(0,o.kt)("inlineCode",{parentName:"h3"},"value")),(0,o.kt)(l.Z,{type:"string",description:"Phone value.",defaultValue:'""',mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"onchange"},(0,o.kt)("inlineCode",{parentName:"h3"},"onChange")),(0,o.kt)(l.Z,{type:"(phone: string, meta: { country: ParsedCountry, inputValue: string }) => void",description:"Callback that calls on phone change",defaultValue:"undefined",mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"defaultcountry"},(0,o.kt)("inlineCode",{parentName:"h3"},"defaultCountry")),(0,o.kt)(l.Z,{type:"CountryIso2",description:"Default country value (iso2).",defaultValue:'"us"',mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"countries"},(0,o.kt)("inlineCode",{parentName:"h3"},"countries")),(0,o.kt)(l.Z,{type:"CountryData[]",description:"An array of available countries to select (and guess)",defaultValue:"defaultCountries",mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"preferredcountries"},(0,o.kt)("inlineCode",{parentName:"h3"},"preferredCountries")),(0,o.kt)(l.Z,{type:"CountryIso2[]",description:"An array of countries to display at the top of the dropdown list",defaultValue:"[]",mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"hidedropdown"},(0,o.kt)("inlineCode",{parentName:"h3"},"hideDropdown")),(0,o.kt)(l.Z,{type:"boolean",description:"Hide the dropdown icon. Make country selection not accessible.",defaultValue:"false",mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"disabled"},(0,o.kt)("inlineCode",{parentName:"h3"},"disabled")),(0,o.kt)(l.Z,{type:"boolean",description:"Disable phone input and country selector.",defaultValue:"false",mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"prefix"},(0,o.kt)("inlineCode",{parentName:"h3"},"prefix")),(0,o.kt)(l.Z,{type:"string",description:"Prefix for phone value.",defaultValue:'"+"',mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"defaultmask"},(0,o.kt)("inlineCode",{parentName:"h3"},"defaultMask")),(0,o.kt)(l.Z,{type:"string",description:"This mask will apply on countries that does not have specified mask.",defaultValue:'"............"',mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"charafterdialcode"},(0,o.kt)("inlineCode",{parentName:"h3"},"charAfterDialCode")),(0,o.kt)(l.Z,{type:"string",description:"Char that renders after country dial code.",defaultValue:'" "',mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"historysavedebouncems"},(0,o.kt)("inlineCode",{parentName:"h3"},"historySaveDebounceMS")),(0,o.kt)(l.Z,{type:"number",description:"Save value to history if there were not any changes in provided milliseconds timeslot. Undo/redo (ctrl+z/ctrl+shift+z) works only with values that are saved in history",defaultValue:"200",mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"disablecountryguess"},(0,o.kt)("inlineCode",{parentName:"h3"},"disableCountryGuess")),(0,o.kt)(l.Z,{type:"boolean",description:(0,o.kt)("span",null,"Disable country guess on value change. ",(0,o.kt)("code",null,"onCountryGuess")," callback would not be called."),defaultValue:"false",mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"disabledialcodeprefill"},(0,o.kt)("inlineCode",{parentName:"h3"},"disableDialCodePrefill")),(0,o.kt)(l.Z,{type:"boolean",description:"Disable dial code prefill on initialization. Dial code prefill works only when empty phone value have been provided.",defaultValue:"false",mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"forcedialcode"},(0,o.kt)("inlineCode",{parentName:"h3"},"forceDialCode")),(0,o.kt)(l.Z,{type:"boolean",description:"Always display the dial code. Dial code can't be removed/changed by keyboard events, but it can be changed by pasting another country phone value.",defaultValue:"false",mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"disabledialcodeandprefix"},(0,o.kt)("inlineCode",{parentName:"h3"},"disableDialCodeAndPrefix")),(0,o.kt)(l.Z,{type:"boolean",description:(0,o.kt)("span",null,"Display phone value will not include passed ",(0,o.kt)("code",null,"dialCode")," and ",(0,o.kt)("code",null,"prefix")," if set to ",(0,o.kt)("code",null,"true"),". ",(0,o.kt)("code",null,"forceDialCode")," value will be ignored."),defaultValue:"false",mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"showdisableddialcodeandprefix"},(0,o.kt)("inlineCode",{parentName:"h3"},"showDisabledDialCodeAndPrefix")),(0,o.kt)(l.Z,{type:"boolean",description:(0,o.kt)("span",null,"Show prefix and dial code between country selector and phone input. Works only when ",(0,o.kt)("code",null,"disableDialCodeAndPrefix")," is ",(0,o.kt)("code",null,"true")),defaultValue:"false",mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"disablefocusaftercountryselect"},(0,o.kt)("inlineCode",{parentName:"h3"},"disableFocusAfterCountrySelect")),(0,o.kt)(l.Z,{type:"boolean",description:"Disable auto focus on input field after country select.",defaultValue:"false",mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"disableformatting"},(0,o.kt)("inlineCode",{parentName:"h3"},"disableFormatting")),(0,o.kt)(l.Z,{type:"boolean",description:"Disable phone value mask formatting. All formatting characters will not be displayed, but the mask length will be preserved.",defaultValue:"false",mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"flags"},(0,o.kt)("inlineCode",{parentName:"h3"},"flags")),(0,o.kt)(l.Z,{type:"CustomFlagImage[]",description:"Custom flag URLs array",defaultValue:"undefined",mdxType:"PropDescription"}),(0,o.kt)("h3",{id:"inputprops"},(0,o.kt)("inlineCode",{parentName:"h3"},"inputProps")),(0,o.kt)(l.Z,{type:"InputHTMLAttributes",description:"Default input component props",defaultValue:"undefined",mdxType:"PropDescription"}),(0,o.kt)("admonition",{type:"note"},(0,o.kt)("p",{parentName:"admonition"},"Input props like ",(0,o.kt)("inlineCode",{parentName:"p"},"onFocus"),", ",(0,o.kt)("inlineCode",{parentName:"p"},"onBlur"),", ",(0,o.kt)("inlineCode",{parentName:"p"},"name"),", ",(0,o.kt)("inlineCode",{parentName:"p"},"placeholder"),", ",(0,o.kt)("inlineCode",{parentName:"p"},"disabled"),", ",(0,o.kt)("inlineCode",{parentName:"p"},"required")," and ",(0,o.kt)("inlineCode",{parentName:"p"},"autoFocus")," also supported as top-level props.",(0,o.kt)("br",null),"\nIf you want add some additional attributes to the input element, you can do it using ",(0,o.kt)("inlineCode",{parentName:"p"},"inputProps"))),(0,o.kt)("h2",{id:"style-properties"},"Style properties"),(0,o.kt)("table",null,(0,o.kt)("thead",{parentName:"table"},(0,o.kt)("tr",{parentName:"thead"},(0,o.kt)("th",{parentName:"tr",align:null},"Prop"),(0,o.kt)("th",{parentName:"tr",align:null},"Type"),(0,o.kt)("th",{parentName:"tr",align:null},"Description"))),(0,o.kt)("tbody",{parentName:"table"},(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:null},"style"),(0,o.kt)("td",{parentName:"tr",align:null},(0,o.kt)("inlineCode",{parentName:"td"},"CSSProperties")),(0,o.kt)("td",{parentName:"tr",align:null},"Custom styles for ",(0,o.kt)("strong",{parentName:"td"},"PhoneInput container"))),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:null},"className"),(0,o.kt)("td",{parentName:"tr",align:null},(0,o.kt)("inlineCode",{parentName:"td"},"string")),(0,o.kt)("td",{parentName:"tr",align:null},"Custom className for ",(0,o.kt)("strong",{parentName:"td"},"PhoneInput container"))),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:null},"inputStyle"),(0,o.kt)("td",{parentName:"tr",align:null},(0,o.kt)("inlineCode",{parentName:"td"},"CSSProperties")),(0,o.kt)("td",{parentName:"tr",align:null},"Custom styles for ",(0,o.kt)("strong",{parentName:"td"},"input field"))),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:null},"inputClassName"),(0,o.kt)("td",{parentName:"tr",align:null},(0,o.kt)("inlineCode",{parentName:"td"},"string")),(0,o.kt)("td",{parentName:"tr",align:null},"Custom className for ",(0,o.kt)("strong",{parentName:"td"},"input field"))),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:null},"countrySelectorStyleProps"),(0,o.kt)("td",{parentName:"tr",align:null},(0,o.kt)("a",{parentName:"td",href:"/docs/Subcomponents%20API/CountrySelector#properties"},(0,o.kt)("inlineCode",{parentName:"a"},"CountrySelectorStyleProps"))),(0,o.kt)("td",{parentName:"tr",align:null},"Style properties for ",(0,o.kt)("strong",{parentName:"td"},"country selector"))),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:null},"dialCodePreviewStyleProps"),(0,o.kt)("td",{parentName:"tr",align:null},(0,o.kt)("a",{parentName:"td",href:"/docs/Subcomponents%20API/DialCodePreview#properties"},(0,o.kt)("inlineCode",{parentName:"a"},"DialCodePreviewStyleProps"))),(0,o.kt)("td",{parentName:"tr",align:null},"Style properties for ",(0,o.kt)("strong",{parentName:"td"},"dial code preview"))))),(0,o.kt)("h2",{id:"css-variables"},"CSS variables"),(0,o.kt)("table",null,(0,o.kt)("thead",{parentName:"table"},(0,o.kt)("tr",{parentName:"thead"},(0,o.kt)("th",{parentName:"tr",align:null},"Variable"),(0,o.kt)("th",{parentName:"tr",align:null},"Default value"))),(0,o.kt)("tbody",{parentName:"table"},(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:null},"--react-international-phone-height"),(0,o.kt)("td",{parentName:"tr",align:null},(0,o.kt)("inlineCode",{parentName:"td"},"36px"))),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:null},"--react-international-phone-background-color"),(0,o.kt)("td",{parentName:"tr",align:null},(0,o.kt)("inlineCode",{parentName:"td"},"white"))),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:null},"--react-international-phone-text-color"),(0,o.kt)("td",{parentName:"tr",align:null},(0,o.kt)("inlineCode",{parentName:"td"},"#222"))),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:null},"--react-international-phone-font-size"),(0,o.kt)("td",{parentName:"tr",align:null},(0,o.kt)("inlineCode",{parentName:"td"},"13px"))),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:null},"--react-international-phone-border-radius"),(0,o.kt)("td",{parentName:"tr",align:null},(0,o.kt)("inlineCode",{parentName:"td"},"4px "))),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:null},"--react-international-phone-border-color"),(0,o.kt)("td",{parentName:"tr",align:null},(0,o.kt)("inlineCode",{parentName:"td"},"gainsboro"))),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:null},"--react-international-phone-disabled-background-color"),(0,o.kt)("td",{parentName:"tr",align:null},(0,o.kt)("inlineCode",{parentName:"td"},"whitesmoke"))),(0,o.kt)("tr",{parentName:"tbody"},(0,o.kt)("td",{parentName:"tr",align:null},"--react-international-phone-disabled-text-color"),(0,o.kt)("td",{parentName:"tr",align:null},(0,o.kt)("inlineCode",{parentName:"td"},"#666"))))),(0,o.kt)("admonition",{type:"info"},(0,o.kt)("p",{parentName:"admonition"},"You can find more styling properties and CSS variables in ",(0,o.kt)("a",{parentName:"p",href:"/docs/subcomponents%20API/"},"Subcomponents"))),(0,o.kt)("h2",{id:"ref-forwarding"},"Ref forwarding"),(0,o.kt)("p",null,"You can pass ref to a PhoneInput component.",(0,o.kt)("br",null),"\nRef object refers to inner ",(0,o.kt)("strong",{parentName:"p"},"input element")," with some additional properties."),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-tsx"},"const PhoneWithRef = () => {\n  const ref = useRef(null);\n  return (\n    <PhoneInput ref={ref}>;\n  )\n}\n")),(0,o.kt)("admonition",{type:"note"},(0,o.kt)("p",{parentName:"admonition"},"If you use typescript you should use ",(0,o.kt)("inlineCode",{parentName:"p"},"PhoneInputRefType")," for as ref type:"),(0,o.kt)("pre",{parentName:"admonition"},(0,o.kt)("code",{parentName:"pre",className:"language-tsx"},"import { PhoneInputRefType } from 'react-international-phone';\n// ...\nconst ref = useRef<PhoneInputRefType>(null);\n"))),(0,o.kt)("h3",{id:"ref-additional-properties"},"Ref additional properties"),(0,o.kt)("p",null,"In addition to the ",(0,o.kt)("a",{parentName:"p",href:"https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement"},"HTMLInputElement API"),", ref also allows you to use these methods:"),(0,o.kt)("h4",{id:"setcountry"},(0,o.kt)("inlineCode",{parentName:"h4"},"setCountry")),(0,o.kt)(l.Z,{type:"(iso2: CountryIso2, options?: { focusOnInput: boolean }) => void",description:"Set some country value (works same as country selector country item click handler)",mdxType:"PropDescription"}),(0,o.kt)("h4",{id:"state"},(0,o.kt)("inlineCode",{parentName:"h4"},"state")),(0,o.kt)(l.Z,{type:"{ phone: string; inputValue: string; country: ParsedCountry }",description:"State of the phone input",mdxType:"PropDescription"}),(0,o.kt)("h2",{id:"parsedcountry-type"},(0,o.kt)("inlineCode",{parentName:"h2"},"ParsedCountry")," type"),(0,o.kt)("p",null,(0,o.kt)("inlineCode",{parentName:"p"},"onChange")," callback provides ",(0,o.kt)("inlineCode",{parentName:"p"},"country")," object with ",(0,o.kt)("inlineCode",{parentName:"p"},"ParsedCountry")," type:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-ts"},"interface ParsedCountry {\n  name: string;\n  iso2: CountryIso2;\n  dialCode: string;\n  format: FormatConfig | string | undefined;\n  priority: number | undefined;\n  areaCodes: string[] | undefined;\n}\n")),(0,o.kt)("p",null,"Parsed country object example:"),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-ts"},"{\n  name: 'Ukraine';\n  iso2: 'ua';\n  dialCode: '380';\n  format: '(..) ... .. ..';\n  priority: undefined;\n  areaCodes: undefined;\n}\n")))}m.isMDXComponent=!0}}]);