Next.js와 Styled-Components 사용 시 Unknown Prop Warning 해결하기

1. 문제 상황

Next.js 프로젝트에서 styled-components를 사용해 스타일링을 적용하던 중, 다음과 같은 경고 메시지가 콘솔에 출력되었습니다.

styled-components: it looks like an unknown prop "bold" is being sent through to the DOM, which will likely trigger a React console error. If you would like automatic filtering of unknown props, you can opt-into that behavior via `<StyleSheetManager shouldForwardProp={...}>` (connect an API like `@emotion/is-prop-valid`) or consider using transient props (`$` prefix for automatic filtering.)
...

2. 원인 분석

styled-components가 HTML DOM에 표준 속성이 아닌 props(bold, gray, paddingLeft)를 전달하면서 해당 경고가 발생합니다.
React는 HTML DOM에 표준 속성이 아닌 props가 포함되면 경고를 표시하는데, HTML <div>요소에 bold 같은 속성은 없기 때문에 경고가 발생하게 되는 것 입니다.

3. 해결방법 : Transient Props 사용하기

이 문제를 해결하기 위해 styled-components에서 제공하는 Transient Props 기능을 사용했습니다. Props는 props 앞에 $를 붙여주면 해당 props가 DOM에 전달되지 않도록 자동으로 필터링해 줍니다.

수정 전 코드

const StyledText = styled.div<StyledTextProps>`
    font-family: ${(props) => props.theme.fonts.HangeulFontRegular};

    ${(props) =>
        props.bold &&
        css`
            font-weight: bold;
            font-size: ${props.theme.fontSizes.medium};
        `}

    ${(props) =>
        props.gray &&
        css`
            color: gray;
            margin-left: 20px;
            padding: 10px;
            font-size: 17px;
        `}

    ${(props) =>
        props.paddingLeft &&
        css`
            padding-left: 30px;
        `}
`;

<StyledText bold> TEXT1 </StyledText>
<StyledText bold paddingLeft> TEXT2 </StyledText>

수정 후 코드

const StyledText = styled.div<StyledTextProps>`
    font-family: ${(props) => props.theme.fonts.HangeulFontRegular};

    ${(props) =>
        props.$bold &&
        css`
            font-weight: bold;
            font-size: ${props.theme.fontSizes.medium};
        `}

    ${(props) =>
        props.$gray &&
        css`
            color: gray;
            margin-left: 20px;
            padding: 10px;
            font-size: 17px;
        `}

    ${(props) =>
        props.$paddingLeft &&
        css`
            padding-left: 30px;
        `}
`;

<StyledText $bold> TEXT1 </StyledText>
<StyledText $bold $paddingLeft> TEXT2 </StyledText>